Forem: Annastacia Kioko

Integrating Africa's Talking (SMS) in your Rails Application

Annastacia Kioko — Fri, 12 Apr 2024 10:18:49 +0000

Pre-requisites

Knowledge of Ruby on Rails

Africa's Talking

If you don't have an account, you can sign up here
Follow the registration process and activate your account.
By default AT( Africa's Talking) provides you with a sandbox account, you can use this to test your application.
On the menu on your left, click on settings and click on API Key, enter your password and click on generate API key.
This will generate an API key for your sandbox account, copy this key and keep it safe.
Default username for sandbox account is sandbox

For production, you need to first create a team, and within the team, you can create a new app. Give your app a name, username, select your country and currency then save.
To get your API key, click on the app you just created, and click on settings, then click on API Key, enter your password and click on generate API key.

Rails Application

In your Rails application, add the africastalking-ruby gem to your Gemfile and run bundle install
You can add the key and username to your environment variables or to your credentials file.
For this tutorial I'll be using the credentials file, to create a new credentials file, run EDITOR="nano" rails credentials:edit in your terminal.
Add the following to your credentials file:

  africas_talking:
    sandbox_username: 'sandbox'
    sandbox_api_key: 'your_sandbox_api_key'
    prod_username: 'your_prod_username'
    prod_api_key: 'your_prod_api_key'

Make sure to substitute your_sandbox_api_key, your_prod_username and your_prod_api_key with your actual keys.
At this point, you can test if your credentials from the console, open your console and run the following:

require 'AfricasTalking'

username = Rails.application.credentials.africas_talking[:sandbox_username]
api_key = Rails.application.credentials.africas_talking[:sandbox_api_key]

@at=AfricasTalking::Initialize.new(username, api_key)

@at.sms.send('to' => '07xxxxxxxx', 'message' => 'message')

NOTE

If you use sandbox credentials, the message isn't actually sent to the phone number, it's just a simulation.You can use the Launch a Simulator feature on the AT dashboard to see the message. Enter the phone number you want to send the message to, connect then send the message from your console.
A successful response might look like this

[#<StatusReport:0x00007fe8c9d47358
  @cost="KES 0.8000",
  @messageId="ATXid_e5b768b6d7bb4b5f45c4b40399fd1bab",
  @number="07xxxxxxxx",
  @status="Success"
>]

A failure response might look like this

[#<StatusReport:0x00007fe8c9e9b880
  @cost="0",
  @messageId="None",
  @number="7xxxxxxxx",
  @status="InvalidPhoneNumber"
>]

For Kenyan numbers, the valid formats are 2547xxxxxxxx or 07xxxxxxxx or +2547xxxxxxx

Implementation

Let's create an AT module which will handle all Africas Talking related tasks. Create a file in lib/modules/africastalking.rb and add the following:

require 'AfricasTalking'

class Africastalking
  def initialize
    if Rails.env.production?
      username = Rails.application.credentials.africas_talking[:prod_username]
      api_key = Rails.application.credentials.africas_talking[:prod_api_key]
    else
      username = Rails.application.credentials.africas_talking[:sandbox_username]
      api_key = Rails.application.credentials.africas_talking[:sandbox_api_key]
    end

    at = AfricasTalking::Initialize.new(username, api_key)
    @sms = at.sms
  end

  def self.send_sms(**options)
    new.send_sms(**options)
  end

  def send_sms(**options)
    message = options[:message]
    to = options[:to]

    @sms.send(
      'to' => to,
      'message' => message,
      'retryDurationInHours' => 1
    )
  end
end

message and to are REQUIRED options while retryDurationInHours is optional, it specifies the number of hours for our message to be retried incase it's not delivered.
Other optional arguments are from which is the senders ID ( by default it is 'AFRICASTKNG') that you can register with Africa's Talking. To see what other options you can pass, check AT's Github Documentation
We initialize the Africastalking class with the username and api key from our credentials file, we then create a new instance of the Africastalking class and call the send_sms method with the message and to options.

Usage

In this example, I have set up a simple User model that only takes in a name and phone_number and a model Broadcast Message that has a message and a status. We will create a broadcast message and send it to all the users in our database.
In my broadcast_messages_controller.rb (or wherever you want to send the message from), I'll define an action send_sms that will send the message to all the users in our database.This action will in turn call a service object that will handle sending the message to all the users in our database.

def send_sms
  BulkSendSms.new(broadcast_message_id: @broadcast_message.id).call
end

On the index page I list all the broadcast messages and have a button to send the message to all the users in the database.

I have created a service object BulkSendSms that will handle sending the message to all the users in our database. Create a new file in app/services and name it bulk_send_sms.rb and add the following:

require './lib/modules/africastalking'

class BulkSendSms

  attr_reader :broadcast_message_id, :broadcast_message, :users

  def initialize(params={})
    @broadcast_message_id = params[:broadcast_message_id] || params['broadcast_message_id']
    @success_count = 0
    @failure_count = 0
    @failure_reasons = []
  end

  def call
    puts '[Service] Bulk sending broadcast sms called..'

    load_broadcast_message
    load_users
    send_sms
    results
  end

  private

  def load_broadcast_message
    @broadcast_message = BroadcastMessage.find(broadcast_message_id)

    if broadcast_message.blank?
      puts 'No broadcast message found'
      return false
    end

    puts "Loaded broadcast message - #{broadcast_message.message}"
  end

  def load_users
    return if broadcast_message.blank?
    @users = User.all

    if users.empty?
      puts 'No users found'
      return false
    end

    puts "Loaded #{users.size} users"
  end

  def send_sms
    return if users.empty?

    users.each do |user|
      puts "Sending SMS to #{user.name} with phone - #{user.phone_number}"
      request = Africastalking.send_sms(
        message: Liquid::Template.parse(broadcast_message.message).render(
          "name" => user.name
        ),
        to: user.phone_number
      )

      puts request

      if request[0].status == 'Success'
        @success_count += 1
        puts 'SMS sent successfully'
      else
        @failure_count += 1
        puts 'Failed to send SMS'
        @failure_reasons << "#{request[0].status} - #{request[0].number} for #{user.name}"
      end
    end
  end

  def results
    @broadcast_message.update(status: :sent)

    total_count = users.size
    puts "Successfully sent to #{@success_count} out of #{total_count} users"

    if failure_count > 0
      puts "Failed to send to #{@failure_count} users, reasons: #{@failure_reasons.join(', ')}"
    end
  end

end

I initiate success_count, failure_count and failure_reasons to keep track of the number of messages sent successfully, the number of messages that failed to send and the reasons for the failure respectively.
We then load the broadcast message and users from the database, if the broadcast message is not found or there are no users in the database, we return false.
In the send_sms method, we loop through all the users in the database and send the message to each user. We use the Liquid gem to parse the message and render the user's name in the message.We then call the Africastalking send_sms method we defined earlier in the Africastalking module and pass in the message and the user's phone number.
In the results method, we update the broadcast message status to sent and print out the number of messages sent successfully and the number of messages that failed to send and the reasons for the failure.Instead of logging you can create a report and send it to your email or the notifcation model or any other way you prefer.

Conclusion

You can now send SMS to all the users in your database using Africas Talking API. You can also extend this to send SMS to a specific group of users or to send SMS to a single user. You can also add more options to the send_sms method to allow for more customization of the message.
For improvements, we can use a worker to send the messages in the background to avoid blocking the main thread. We can also set up webhooks to get delivery reports and handle failed messages.

You can find the full code here

Thank you for reading this tutorial, I hope you found it helpful. If you have any questions or suggestions, feel free to reach out to me on Email or LinkedIn

Cart Functionality in React with Context API

Annastacia Kioko — Sun, 04 Jun 2023 08:26:26 +0000

Implementing Cart Functionality in React JS

Introduction

In this tutorial, we will be implementing a cart functionality in React JS. We will be using React Hooks to manage the state of the cart. We will be using the Context API to pass the cart state to the components that need it. We will be using the Local Storage API to persist the cart state in the browser.We will also be using Tailwind CSS to style our application.

Prerequisites

To follow along with this tutorial, you will need to have the following installed on your machine:

Node.js
npm

You also need to have a basic understanding of React JS and Tailwind CSS.

Getting Started

To get started, we will create a new React application using vite. To do this, run the following command in your terminal:



npm create vite@latest

You will be prompted to enter the name of your project. Enter the name of your project and press enter. In this tutorial, we will be naming our project react-cart. You will also be prompted to select a framework. Select React and press enter. You will also be prompted to select a variant. Select Javascript and press enter. This will create a new React application in a folder named react-cart. To start the application, navigate to the react-cart folder cd react-cart and run the following command in your terminal:



npm run dev

This will start the application in development mode. You can now open the application in your browser by navigating to http://localhost:5173.

Installing Tailwind CSS

To install Tailwind CSS, run the following command in your terminal:



npm install -D tailwindcss postcss autoprefixer



npx tailwindcss init -p

This will create a tailwind.config.js file in the root of your project. Open the tailwind.config.js file and add the following code to it:



/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Next, let's clean up the index.css file in the src folder. Open the index.css file and remove all the code in it. Next, add the following code to the index.css file:



@tailwind base;
@tailwind components;
@tailwind utilities;

Let's also clear up the App.jsx file in the src folder so that it looks like this:



function App() {
  return (
    <>
    </>
  )
}

You can also delete the App.css file in the src folder.

Creating the Products Component

Let's create a new folder named components in the src folder. Inside the components folder, create a new file named Products.jsx.
We will be using the Dummy Json to get the products that we will be displaying in our application. To fetch the products, we will be using the useEffect hook. We will also be using the useState hook to store the products in the state. Let's import the useEffect and useState hooks from the react package. Add the following code to the Products.jsx file:



import { useEffect, useState } from "react";

Create a new function named Products and export it. Add the following code to the Products.jsx file:



export default function Products() {
  return (
    <>
    </>
  )
}

Let's initialize the state of the products. Add the following code to the Products.jsx file:



const [products, setProducts] = useState([]);

Next, let's fetch the products.We will use an async function to fetch the products. Add the following code to the Products.jsx file:



async function getProducts() {
    const response = await fetch('https://dummyjson.com/products')  // fetch the products
    const data = await response.json() // convert the response to json
    setProducts(data.products) // set the products in the state to the products we fetched
  }

Next, let's call the getProducts function in the useEffect hook. Add the following code to the Products.jsx file:



useEffect(() => {
    getProducts()
  }, [])

Next, let's display the products in the Products component. In the return statement of the Products component, add the following code:



<div className='flex flex-col justify-center bg-gray-100'>
  <div className='flex justify-between items-center px-20 py-5'>
    <h1 className='text-2xl uppercase font-bold mt-10 text-center mb-10'>Shop</h1>
  </div>
  <div className='grid sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4 px-10'>
    {
      products.map(product => (
        <div key={product.id} className='bg-white shadow-md rounded-lg px-10 py-10'>
          <img src={product.thumbnail} alt={product.title} className='rounded-md h-48' />
          <div className='mt-4'>
            <h1 className='text-lg uppercase font-bold'>{product.title}</h1>
            <p className='mt-2 text-gray-600 text-sm'>{product.description.slice(0, 40)}...</p>
            <p className='mt-2 text-gray-600'>${product.price}</p>
          </div>
          <div className='mt-6 flex justify-between items-center'>
            <button className='px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700'>Add to cart</button>
          </div>
        </div>
      ))
    }
  </div>
</div>

This will display a card for each product. Each card will display the product image, title, description, and price. Each card will also have a button that will be used to add the product to the cart.

Navigate to App.jsx and import the Products component. Add the following code to the App.jsx file:



import Products from './components/Products'

Next, let's display the Products component in the App component. In the return statement of the App component, add the following code:



<Products />

Your App.jsx file should now look like this:



import Products from './components/Products'

function App() {
  return (
    <Products />
  )
}

export default App

Your Products.jsx file should now look like this:



import { useState, useEffect } from 'react'


export default function Products() {
  const [products, setProducts] = useState([])

  async function getProducts() {
    const response = await fetch('https://dummyjson.com/products')
    const data = await response.json()
    setProducts(data.products)
  }

  useEffect(() => {
    getProducts()
  }, [])

  return (
    <div className='flex flex-col justify-center bg-gray-100'>
      <div className='flex justify-between items-center px-20 py-5'>
        <h1 className='text-2xl uppercase font-bold mt-10 text-center mb-10'>Shop</h1>
        <h1 className='text-2xl uppercase font-bold mt-10 text-center mb-10'>Cart</h1>
      </div>
      <div className='grid sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4 px-10'>
        {
          products.map(product => (
            <div key={product.id} className='bg-white shadow-md rounded-lg px-10 py-10'>
              <img src={product.thumbnail} alt={product.title} className='rounded-md h-48' />
              <div className='mt-4'>
                <h1 className='text-lg uppercase font-bold'>{product.title}</h1>
                <p className='mt-2 text-gray-600 text-sm'>{product.description.slice(0, 40)}...</p>
                <p className='mt-2 text-gray-600'>${product.price}</p>
              </div>
              <div className='mt-6 flex justify-between items-center'>
                <button className='px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700'>Add to cart</button>
              </div>
            </div>
          ))
        }
      </div>
    </div>
  )
}

Open the application in your browser and you should see the products displayed.

Creating the Cart Context

Context is a way to pass data through the component tree without having to pass props down manually at every level. In this tutorial, we will be using the Context API to pass the cart state to the components that need it. Let's create a new folder named context in the src folder. Inside the context folder, create a new file named cart.jsx. We will be using the createContext hook to create the cart context.We will also be using the useState hook to store the cart state and the useEffect hook to persist the cart state in the browser. Let's import the createContext, useState, and useEffect hooks from the react package. Add the following code to the cart.jsx file:



import { createContext, useState, useEffect } from 'react'

Next, let's create the cart context. Add the following code to the cart.jsx file:



export const CartContext = createContext()

Next, let's create the CartProvider component. Add the following code to the cart.jsx file:



export const CartProvider = ({ children }) => {
}

Initialize the state of the cart. Add the following code to the cart.jsx file:



const [cartItems, setCartItems] = useState([])

Looking at how we want our cart to work, we want to be able to add items to the cart, remove items from the cart, and clear the cart. Let's create a function that will be used to add items to the cart. Add the following code to the cart.jsx file:



 const addToCart = (item) => {
  const isItemInCart = cartItems.find((cartItem) => cartItem.id === item.id); // check if the item is already in the cart

  if (isItemInCart) {
  setCartItems(
      cartItems.map((cartItem) => // if the item is already in the cart, increase the quantity of the item
      cartItem.id === item.id
          ? { ...cartItem, quantity: cartItem.quantity + 1 }
          : cartItem // otherwise, return the cart item
      )
  );
  } else {
  setCartItems([...cartItems, { ...item, quantity: 1 }]); // if the item is not in the cart, add the item to the cart
  }
};

Explanation:

We are using the find method to check if the item is already in the cart. The find method returns the value of the first element in the array that satisfies the provided testing function. If no values satisfy the testing function, undefined is returned.
If the item is already in the cart, we are using the map method to increase the quantity of the item in the cart. The map method creates a new array populated with the results of calling a provided function on every element in the calling array.
If the item is not in the cart, we are using the spread operator to add the item to the cart.

Let's create a function that will be used to remove items from the cart. Add the following code to the cart.jsx file:



 const removeFromCart = (item) => {
  const isItemInCart = cartItems.find((cartItem) => cartItem.id === item.id);

  if (isItemInCart.quantity === 1) {
    setCartItems(cartItems.filter((cartItem) => cartItem.id !== item.id)); // if the quantity of the item is 1, remove the item from the cart
  } else {
    setCartItems(
      cartItems.map((cartItem) =>
        cartItem.id === item.id
          ? { ...cartItem, quantity: cartItem.quantity - 1 } // if the quantity of the item is greater than 1, decrease the quantity of the item
          : cartItem
      )
    );
  }
};

Explanation:

We are using the find method to check if the item is in the cart. The find method returns the value of the first element in the array that satisfies the provided testing function. If no values satisfy the testing function, undefined is returned.
If the quantity of the item is 1, we are using the filter method to remove the item from the cart. The filter method creates a new array with all elements that pass the test implemented by the provided function.
If the quantity of the item is greater than 1, we are using the map method to decrease the quantity of the item in the cart. The map method creates a new array populated with the results of calling a provided function on every element in the calling array.

Let's create a function that will be used to clear the cart. Add the following code to the cart.jsx file:



const clearCart = () => {
  setCartItems([]); // set the cart items to an empty array
};

Explanation:

We are using the setCartItems method to set the cart items to an empty array.

Let's create a function to get the cart total. Add the following code to the cart.jsx file:



const getCartTotal = () => {
  return cartItems.reduce((total, item) => total + item.price * item.quantity, 0); // calculate the total price of the items in the cart
};

Explanation of the code above:

We are using the reduce method to calculate the total price of the items in the cart. The reduce method executes a reducer function (that you provide) on each element of the array, resulting in a single output value.

Next, let's use the useEffect hook to persist the cart state in the browser. Add the following code to the cart.jsx file:



useEffect(() => {
  localStorage.setItem("cartItems", JSON.stringify(cartItems));
}, [cartItems]);

Explanation:

We are using the setItem method of the localStorage API to set the cart items in the browser. The setItem method sets the value of the specified localStorage item.
We are using the JSON.stringify method to convert the cart items to a string. The JSON.stringify method converts a JavaScript object or value to a JSON string.
For a real-world application, you will need to use a database to store the cart items, since the localStorage API is not secure and can be easily manipulated by the user.

Let's also use the useEffect hook to get the cart items from the browser. Add the following code to the cart.jsx file:



useEffect(() => {
    const cartItems = localStorage.getItem("cartItems");
    if (cartItems) {
    setCartItems(JSON.parse(cartItems));
    }
}, []);

Explanation:

We are using the getItem method of the localStorage API to get the cart items from the browser. The getItem method returns the value of the specified localStorage item.
We are using the JSON.parse method to convert the cart items to an object. The JSON.parse method parses a JSON string, constructing the JavaScript value or object described by the string.

Let's update the initial state of cart items to the cart items we get from the browser. Add the following code to the cart.jsx file:



const [cartItems, setCartItems] = useState(localStorage.getItem('cartItems') ? JSON.parse(localStorage.getItem('cartItems')) : [])

This will set the initial state of the cart items to the cart items we get from the browser. If there are no cart items in the browser, the initial state of the cart items will be an empty array.

Next, let's pass the cart state to the components that need it. Add the following code to the cart.jsx file:



return (
  <CartContext.Provider
    value={{
      cartItems,
      addToCart,
      removeFromCart,
      clearCart,
      getCartTotal,
    }}
  >
    {children}
  </CartContext.Provider>
);

Your cart.jsx file should now look like this:



import { createContext, useState, useEffect } from 'react'

export const CartContext = createContext()

export const CartProvider = ({ children }) => {
  const [cartItems, setCartItems] = useState(localStorage.getItem('cartItems') ? JSON.parse(localStorage.getItem('cartItems')) : [])

  const addToCart = (item) => {
    const isItemInCart = cartItems.find((cartItem) => cartItem.id === item.id);

    if (isItemInCart) {
      setCartItems(
        cartItems.map((cartItem) =>
          cartItem.id === item.id
            ? { ...cartItem, quantity: cartItem.quantity + 1 }
            : cartItem
        )
      );
    } else {
      setCartItems([...cartItems, { ...item, quantity: 1 }]);
    }
  };

  const removeFromCart = (item) => {
    const isItemInCart = cartItems.find((cartItem) => cartItem.id === item.id);

    if (isItemInCart.quantity === 1) {
      setCartItems(cartItems.filter((cartItem) => cartItem.id !== item.id));
    } else {
      setCartItems(
        cartItems.map((cartItem) =>
          cartItem.id === item.id
            ? { ...cartItem, quantity: cartItem.quantity - 1 }
            : cartItem
        )
      );
    }
  };

  const clearCart = () => {
    setCartItems([]);
  };

  const getCartTotal = () => {
    return cartItems.reduce((total, item) => total + item.price * item.quantity, 0);
  };

  useEffect(() => {
    localStorage.setItem("cartItems", JSON.stringify(cartItems));
  }, [cartItems]);

  useEffect(() => {
    const cartItems = localStorage.getItem("cartItems");
    if (cartItems) {
      setCartItems(JSON.parse(cartItems));
    }
  }, []);

  return (
    <CartContext.Provider
      value={{
        cartItems,
        addToCart,
        removeFromCart,
        clearCart,
        getCartTotal,
      }}
    >
      {children}
    </CartContext.Provider>
  );
};

Using the Cart Context

Now that we have created the cart context, let's wrap the App component with the CartProvider component. Open the main.jsx file in the src folder and import the CartProvider component. Add the following code to the main.jsx file:



import { CartProvider } from './context/cart'

Next, let's wrap the App component with the CartProvider component. Add the following code to the main.jsx file:



<CartProvider>
  <App />
</CartProvider>

Your main.jsx file should now look like this:



import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'
import './index.css'
import { CartProvider } from './context/cart.jsx'

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <CartProvider>
      <App />
    </CartProvider>
  </React.StrictMode>,
)

Next, let's import the CartContext from the cart file in the context folder. Add the following code to the Products.jsx file:



import { CartContext } from '../context/cart'

We will also need to import the useContext hook from the react package. Update the import statement in the Products.jsx file to look like this:



import { useContext, useEffect, useState } from 'react'

Next, let's use the useContext hook to get the cart state. Add the following code to the Products.jsx file:



const { cartItems, addToCart } = useContext(CartContext)

Next, let's update the addToCart button to use the addToCart function from the cart context. Update the addToCart button to look like this:



<button onClick={() => addToCart(product)} className='px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700'>Add to cart</button>

Now the button should add the product to the cart when clicked, but it's hard to visualize this without a cart page.
Let's start by creating a Cart component. Create a new file named Cart.jsx in the components folder. We will be using the useContext hook to get the cart state. Let's import the useContext hook from the react package. Add the following code to the Cart.jsx file:



import { useContext } from 'react'

Next, let's import the CartContext from the cart file in the context folder. Add the following code to the Cart.jsx file:



import { CartContext } from '../context/cart'

Create a new function named Cart and export it. Add the following code to the Cart.jsx file:



export default function Cart() {
  return (
    <>
    </>
  )
}

Let's use the useContext hook to get the cart state. Add the following code to the Cart.jsx file:



const { cartItems, addToCart, removeFromCart, clearCart, getCartTotal } = useContext(CartContext)

Next, let's display the cart items in the Cart component. In the return statement of the Cart component, add the following code:



<div className="flex-col flex items-center bg-white gap-8 p-10 text-black text-sm">
  <h1 className="text-2xl font-bold">Cart</h1>
  <div className="flex flex-col gap-4">
    {cartItems.map((item) => (
      <div className="flex justify-between items-center" key={item.id}>
        <div className="flex gap-4">
          <img src={item.thumbnail} alt={item.title} className="rounded-md h-24" />
          <div className="flex flex-col">
            <h1 className="text-lg font-bold">{item.title}</h1>
            <p className="text-gray-600">{item.price}</p>
          </div>
        </div>
        <div className="flex gap-4">
          <button
            className="px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700"
            onClick={() => {
              addToCart(item)
            }}
          >
            +
          </button>
          <p>{item.quantity}</p>
          <button
            className="px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700"
            onClick={() => {
              removeFromCart(item)
            }}
          >
            -
          </button>
        </div>
      </div>
    ))}
  </div>
  {
    cartItems.length > 0 ? (
      <div className="flex flex-col justify-between items-center">
    <h1 className="text-lg font-bold">Total: ${getCartTotal()}</h1>
    <button
      className="px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700"
      onClick={() => {
        clearCart()
      }}
    >
      Clear cart
    </button>
  </div>
    ) : (
      <h1 className="text-lg font-bold">Your cart is empty</h1>
    )
  }
</div>

This will display the cart items in the cart component. Each cart item will display the item image, title, price, and quantity. Each cart item will also have a button to increase the quantity of the item and a button to decrease the quantity of the item. The cart component will also display the total price of the items in the cart and a button to clear the cart.

You can now choose the best way to navigate to your cart from the products page using the react router. In this tutorial, we will be toggling a modal to display the cart.
In the Products component, let's import the Cart component. Add the following code to the Products.jsx file:



import Cart from './Cart'

Let's also initialize the state of the modal. Add the following code to the Products.jsx file:



const [showModal, setShowModal] = useState(false)

Let's create a function to toggle the modal. Add the following code to the Products.jsx file:



const toggle = () => {
  setShowModal(!showModal)
}

Next, we will add a button to toggle the modal. Add the following code to the Products.jsx file below the h1 tag:



{!showModal && <button className='px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700'
  onClick={toggle}
>Cart ({cartItems.length})</button>}

This will display a button to toggle the modal. The button will display the number of items in the cart.

Let's now display the modal( Cart component) when the button is clicked. Add the following code to the Products.jsx file just before the last closing div tag:



  <Cart showModal={showModal} toggle={toggle} />

Your Products.jsx file should now look like this:



import { useState, useEffect, useContext } from 'react'
import { CartContext } from '../context/cart.jsx'
import Cart from './Cart.jsx'


export default function Products() {
  const [showModal, setshowModal] = useState(false);
  const [products, setProducts] = useState([])
  const { cartItems, addToCart } = useContext(CartContext)

  const toggle = () => {
    setshowModal(!showModal);
  };

  async function getProducts() {
    const response = await fetch('https://dummyjson.com/products')
    const data = await response.json()
    setProducts(data.products)
  }

  useEffect(() => {
    getProducts()
  }, [])

  return (
    <div className='flex flex-col justify-center bg-gray-100'>
      <div className='flex justify-between items-center px-20 py-5'>
        <h1 className='text-2xl uppercase font-bold mt-10 text-center mb-10'>Shop</h1>
        {!showModal && <button className='px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700'
          onClick={toggle}
        >Cart ({cartItems.length})</button>}
      </div>
      <div className='grid sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4 px-10'>
        {
          products.map(product => (
            <div key={product.id} className='bg-white shadow-md rounded-lg px-10 py-10'>
              <img src={product.thumbnail} alt={product.title} className='rounded-md h-48' />
              <div className='mt-4'>
                <h1 className='text-lg uppercase font-bold'>{product.title}</h1>
                <p className='mt-2 text-gray-600 text-sm'>{product.description.slice(0, 40)}...</p>
                <p className='mt-2 text-gray-600'>${product.price}</p>
              </div>
              <div className='mt-6 flex justify-between items-center'>
                <button className='px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700'
                  onClick={() => {
                    addToCart(product)
                  }
                  }
                >Add to cart</button>
              </div>
            </div>
          ))
        }
      </div>
      <Cart showModal={showModal} toggle={toggle} />
    </div>
  )
}

Let's update the Cart component to use the showModal prop. Open the Cart.jsx file and update the Cart component to look like this:



import PropTypes from 'prop-types'
import { useContext } from 'react'
import { CartContext } from '../context/cart.jsx'

export default function Cart ({showModal, toggle}) {

  const { cartItems, addToCart, removeFromCart, clearCart, getCartTotal } = useContext(CartContext)


  return (
    showModal && (
      <div className="flex-col flex items-center fixed inset-0 left-1/4 bg-white dark:bg-black gap-8  p-10  text-black dark:text-white font-normal uppercase text-sm">
        <h1 className="text-2xl font-bold">Cart</h1>
        <div className="absolute right-16 top-10">
          <button
            className="px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700"
            onClick={toggle}
          >
            Close
          </button>
        </div>
        <div className="flex flex-col gap-4">
          {cartItems.map((item) => (
            <div className="flex justify-between items-center" key={item.id}>
              <div className="flex gap-4">
                <img src={item.thumbnail} alt={item.title} className="rounded-md h-24" />
                <div className="flex flex-col">
                  <h1 className="text-lg font-bold">{item.title}</h1>
                  <p className="text-gray-600">{item.price}</p>
                </div>
              </div>
              <div className="flex gap-4">
                <button
                  className="px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700"
                  onClick={() => {
                    addToCart(item)
                  }}
                >
                  +
                </button>
                <p>{item.quantity}</p>
                <button
                  className="px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700"
                  onClick={() => {
                    removeFromCart(item)
                  }}
                >
                  -
                </button>
              </div>
            </div>
          ))}
        </div>
        {
          cartItems.length > 0 ? (
            <div className="flex flex-col justify-between items-center">
          <h1 className="text-lg font-bold">Total: ${getCartTotal()}</h1>
          <button
            className="px-4 py-2 bg-gray-800 text-white text-xs font-bold uppercase rounded hover:bg-gray-700 focus:outline-none focus:bg-gray-700"
            onClick={() => {
              clearCart()
            }}
          >
            Clear cart
          </button>
        </div>
          ) : (
            <h1 className="text-lg font-bold">Your cart is empty</h1>
          )
        }
      </div>
    )
  )
}

Cart.propTypes = {
  showModal: PropTypes.bool,
  toggle: PropTypes.func
}

We have added a close button to the cart component. The close button will be used to close the cart component. and I have added some tailwind css classes to the top div to inset the cart component from the left side of the screen.

Conclusion

Our application is now complete. You can open the application in your browser and test it out.

There are other ways you can explore to improve the user experience of the application that I won't cover e.g

The Add to cart button can change to a quantity selector when the product is already added to the cart.
Adding notifications to the application when a user adds/removes an item to the cart.You can use the React Toastify library to add notifications to the application.

I'll implement these features in the source code of the application. You can check it out here
You can also checkout the live demo here

Resources

Thank you for reading this tutorial. If you have any questions, feel free to reach out to me on Email or LinkedIn.

Implementing Google Omniauth In a Rails App

Annastacia Kioko — Fri, 03 Feb 2023 08:07:24 +0000

Omniauth is a ruby gem that allows you to authenticate users with third party services. In this example we will use Google as our third party service. We will use the omniauth-google-oauth2 gem to authenticate users with Google.

Getting Started

To get started we will need to set up an authentication system in our rails app. For this we will use sessions. Sessions are a way to store information about a user in a cookie. This cookie is stored on the users browser and is sent back to the server with every request. This allows us to keep track of the user and their information.
You can check on your browser to see if you have a session cookie by going to the developer tools and looking at the cookies tab. You should see a cookie called _session. This is the cookie that is used to keep track of the user.
For chrome you can go to the developer tools by pressing F12 and then clicking on the Application tab. Then click on the Cookies tab then you should see your domain click on it and you should see your session cookie.
For firefox you can go to the developer tools by pressing F12 and then clicking on the Storage tab. Then click on the Cookies tab then you should see your domain click on it and you should see your session cookie.
In the images below, you can see that before I log in a user I have no session cookie and after I log in I have a session cookie.

Setting up the app

Lets start by creating a new rails app. We will call it omniauth-rails.

rails new omniauth-rails

We will add bcrypt to our gemfile. Bcrypt is a ruby gem that allows us to hash passwords. We will use this to store the users password in the database.

gem 'bcrypt'

Then we will run bundle install to install the gem.

bundle install

Now we will create a user model. We will use the rails generator to create the model.

rails g model User username email password:digest

password:digest will create a password_digest column in the database and add a has_secure_password method to the user model.

class User < ApplicationRecord
  has_secure_password
end

Run the migration to create the users table in the database.

rails db:migrate

Create a controller for the users. We will use the rails generator to create the controller.

rails g controller Users

We will also need to create a controller for the sessions. We will use the rails generator to create the controller.

rails g controller Sessions

Application Controller

Add the following methods to the application controller.

class ApplicationController < ActionController::Base

    def index
        if !logged_in?
            redirect_to login_path
        end
    end

    def current_user
        @current_user ||= User.find(session[:user_id]) if session[:user_id]
    end

    def logged_in?
        current_user
    end

end

The index method will check if the user is logged in. If the user is not logged in we will redirect them to the login page.
The current_user method will check if the session[:user_id] is set. If it is set we will find the user with that id and set it to the @current_user variable. If the session[:user_id] is not set we will return nil.
The logged_in? method will check if the current_user method returns a user. If it does we will return true. If it does not we will return false.

Users Controller

Add the following methods to the users controller.

class UsersController < ApplicationController
  def new
    @user = User.new
  end

  def create
    @user = User.new(user_params)
    if @user.save
      session[:user_id] = @user.id
      redirect_to root_path
    else
      render :new
    end
  end

  private

  def user_params
    params.require(:user).permit(:username, :email, :password, :password_confirmation)
  end
end

The new method will create a new user object. This will be used in the form to create a new user.
The create method will create a new user and save it to the database. If the user is saved we will set the session[:user_id] to the id of the user. This will allow us to keep track of the user. We will then redirect the user to the root path. If the user is not saved we will render the new template.
The user_params method will allow us to get the parameters from the form and only allow the parameters we want to be passed in.

Sessions Controller

Add the following methods to the sessions controller.

class SessionsController < ApplicationController

    def new
       if logged_in?
              redirect_to root_path
         end
    end

    def create
        @user = User.find_by(username: params[:session][:username])
        if @user && @user.authenticate(params[:session][:password])
            session[:user_id] = @user.id
            redirect_to root_path
        else
            flash[:error] = "Invalid username or password"
            redirect_to login_path
        end

    end

    def destroy
        session.delete :user_id
        redirect_to root_path
    end

end

The new method will check if the user is logged in. If the user is logged in we will redirect them to the root path.
The create method will find the user by the username. If the user is found and the password is correct we will set the session[:user_id] to the id of the user. This will allow us to keep track of the user. We will then redirect the user to the root path. If the user is not found or the password is incorrect we will redirect the user to the login page.
The destroy method will delete the session[:user_id] and redirect the user to the root path.

Routes

Add the following routes to the routes.rb file.

Rails.application.routes.draw do
  root 'application#index'
  get '/login', to: 'sessions#new'
  post '/login', to: 'sessions#create'
  delete '/logout', to: 'sessions#destroy'
  get '/signup', to: 'users#new'
  post '/signup', to: 'users#create'
end

The root route will go to the index method in the application controller.
The get '/login', to: 'sessions#new' route will go to the new method in the sessions controller.
The post '/login', to: 'sessions#create' route will go to the create method in the sessions controller.
The delete '/logout', to: 'sessions#destroy' route will go to the destroy method in the sessions controller.
The get '/signup', to: 'users#new' route will go to the new method in the users controller.
The post '/signup', to: 'users#create' route will go to the create method in the users controller.

Views

Now we will create the views for the users and sessions controllers.

mkdir app/views/application
mkdir app/views/users
mkdir app/views/sessions

Application

Create an index.html.erb file in the application folder and add the following code.

<h1> Welcome <%= @current_user.username %>! </h1>
<%= button_to "Logout", logout_path, method: :delete %>

This will display the username of the current user and a logout button.

Users

Create a new.html.erb file in the users folder and add the following code.

<h1> Sign up for a new account </h1>
<%= form_for @user do |f| %>
    <%= f.label :username %>
    <%= f.text_field :username %>
    <%= f.label :email %>
    <%= f.text_field :email %>
    <%= f.label :password %>
    <%= f.password_field :password %>
    <%= f.label :password_confirmation %>
    <%= f.password_field :password_confirmation %>
    <%= f.submit "Sign up" %>
<% end %>

<p>Already have an account? <%= link_to "Login", login_path %></p>

This will display a form to create a new user. It will also display a link to the login page.

Sessions

Create a new.html.erb file in the sessions folder and add the following code.

<h1>Login to your account</h1>
<% if flash[:error] %>
    <p><%= flash[:error] %></p>
<% end %>


<%= form_for :session, url: login_path do |f| %>
    <%= f.label :username %>
    <%= f.text_field :username %>
    <%= f.label :password %>
    <%= f.password_field :password %>
    <%= f.submit "Login" %>
<% end %>

<p>Don't have an account? <%= link_to "Sign up", signup_path %></p>

This will display a form to login to an account. It will also display a link to the signup page.

Your application should now be able to create a new user, login to an existing user, and logout of a user.

GOOGLE OAUTH

First we will need to create a new project in the google developer console.
Go to https://console.developers.google.com/ and under select a project click on new project.
Give your project a name and click create. eg. omniauth-rails
While on the project under APIs & Services click on OAuth consent screen.
Set the user type to external and click create.
On the next page fill out the information and click save.
The app name, user support email, and developer contact information are required.
If your application is in production you will need to add your application url to the authorized domains.You can also upload your app logo, a privacy policy url, and a terms of service url.
Click on save and continue.
On the scopes page, at the moment we don't need to add any scopes. Click on save and continue.
Scopes are used to limit the amount of information that is shared with the application. For example, if you only want the user's email address you can add the scope https://www.googleapis.com/auth/userinfo.email. If you want the user's email address and their profile picture you can add the scope https://www.googleapis.com/auth/userinfo.profile.
Click on save and continue.
On the test users page you can add test users to your application.This means that only the email addresses that you add will be able to login to your application.I will not be adding any test users.
Click on save and continue.
On the summary page you can see all of the information that you have entered. Click on back to dashboard.
On the side dashboard click on credentials and then click on create credentials.
Select OAuth client ID and under application type select web application.
Give your application a name and add http://localhost:3000/auth/google_oauth2/callback to the authorized redirect URIs.If your application is in production add your domain url instead then /auth/google_oauth2/callback.
Click on create.
You will now see your client ID and client secret.

Save this as we will need them later.

Back to our Rails application

Add the following to the Gemfile.

gem 'omniauth'
gem 'omniauth-google-oauth2'
gem 'dotenv-rails'
gem 'omniauth-rails_csrf_protection'

gem 'omniauth' is the main gem that we will be using.
gem 'omniauth-google-oauth2' is the gem that will allow us to use google oauth.
gem 'dotenv-rails' is the gem that will allow us to store our client ID and client secret in a .env file.
gem 'omniauth-rails_csrf_protection' is the gem that will protect against CSRF attacks.

Then run bundle install.

bundle install

Create a .env file in the root directory of our application.

touch .env

and add the following to the .env file.

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret

Remember to add your .env file to your .gitignore file.
Syntax: Note that there are no quotes around the client ID and client secret and no spaces around the equal sign.

Create a new initializer file in the config/initializers directory.

touch config/initializers/omniauth.rb

and add the following to the omniauth.rb file.

Rails.application.config.middleware.use OmniAuth::Builder do
    provider :google_oauth2, ENV['GOOGLE_CLIENT_ID'], ENV['GOOGLE_CLIENT_SECRET'],
end

This is a middleware that will allow us to use omniauth with our application.
The provider method will allow us to use google oauth.
You can also use other providers such as facebook, twitter, github, etc.
You can configure several options, which you pass in to the provider method via a hash:

provider :google_oauth2, ENV['GOOGLE_CLIENT_ID'], ENV['GOOGLE_CLIENT_SECRET'],
    {
        scope: 'email, profile', -- This will allow us to get the user's email address and profile picture.
        prompt: 'select_account', -- This will allow the user to select which account they want to login with.
        image_aspect_ratio: 'square', -- This will make sure that the profile picture is a square.
        image_size: 50, -- This will make sure that the profile picture is 50x50 pixels.
    }

To read more about gem 'omniauth-google-oauth2' go to https://github.com/zquestz/omniauth-google-oauth2.

Remember to restart your server after making any changes to the omniauth.rb file.

Create a migration to add a uid and provider column to the users table.

rails g migration AddUidAndProviderToUsers uid provider

Then run the migration.

rails db:migrate

Let's add a new omniauth action to the sessions controller.

def omniauth
        @user = User.find_or_create_by(uid: request.env['omniauth.auth']['uid'], provider: request.env['omniauth.auth']['provider']) do |u|
            u.username = request.env['omniauth.auth']['info']['name']
            u.email = request.env['omniauth.auth']['info']['email']
            u.password = SecureRandom.hex(10)
        end
        if @user.valid?
            session[:user_id] = @user.id
            redirect_to root_path
        else
            render :new
        end
end

The auth hash is a hash that contains all of the information that we get from the provider.

{
  "provider" => "google_oauth2",
  "uid" => "100000000000000000000",
  "info" => {
    "name" => "John Smith",
    "email" => "john@example.com",
    "first_name" => "John",
    "last_name" => "Smith",
    "image" => "https://lh4.googleusercontent.com/photo.jpg",
    "urls" => {
      "google" => "https://plus.google.com/+JohnSmith"
    }
  },
  ...
}

You can read more about the auth hash at https://github.com/zquestz/omniauth-google-oauth2.
We can access the information by using the hash syntax.
For example, if we want to get the user's email address we can use request.env['omniauth.auth']['info']['email'].
In the omniauth action in the sessions controller we are using the find_or_create_by method to find the user by their uid and provider or create a new user if they don't exist.
We are also using the SecureRandom.hex(10) to set the password.This sets the password to a random string of 10 characters.

Now we will add a new route to the routes.rb file.

get '/auth/:provider/callback', to: 'sessions#omniauth'

This route will allow us to use the omniauth action in the sessions controller.
We use ':provider' to make the route dynamic.This means that we can use this route for any provider. eg facebook, twitter, github, etc.

Now we will add a new button to the login page.
In the app/views/sessions/new.html.erb file add the following.

<h3> Or login with Google</h3>
<%= button_to "Login with Google", "/auth/google_oauth2" %>

This will create a button that will allow the user to login with google.
A button_to is a form that will send a post request to the specified path.

Our application is now ready to use google oauth.
To test it out, run the rails server and go to http://localhost:3000/login.

Check out the live site here.

That's it for this tutorial.Thank you for reading.
Remember to check out the source code on github at https://github.com/Annastacia-dev/omniauth-rails.
Feel free to leave any comments or questions below or reach out to me on email at annetotoh@gmail.com.

Implementing M-pesa STK push and query in Ruby On Rails

Annastacia Kioko — Mon, 12 Dec 2022 07:19:40 +0000

Setup

Daraja

To get started head over to daraja and sign up for a developer account or login if you already have one.
On my apps tab, create a new sandbox app and name it whatever you want, then tick all the check boxes and click on create app.
You will be redirected to the app details page where you will find your consumer key and consumer secret.

Save these somewhere safe as you will need them later.
Navigate to the APIs tab and on M-pesa Express click on Simulate, on the input prompt select the app you just created.
This will auto populate some fields for you, you can leave them as they are.
Scroll down and click on test credentials.

Save your initiator password and passkey somewhere safe as you will need them later.

Ngrok

Go to ngrok and sign up for a free account or login if you already have one.
To install on ubuntu sudo snap install ngrok or download the zip file from the website and extract it.
To connect your account to ngrok run ngrok authtoken <your authtoken> and replace with your authtoken.
We will get back to ngrok later, let's first setup our rails app.

Rails

Create a new rails app rails new <app-name> --api in my case rails new daraja-test --api .
Add the following gems to your gemfile and run bundle install .

gem 'rack-cors'
gem 'rest-client'

We need to create an M-pesa resource, all datatypes are strings.
Run rails g resource Mpesa phoneNumber amount checkoutRequestID merchantRequestID mpesaReceiptNumber .
We also need a model for the access token, run rails g model AccessToken token .
Run rails db:migrate

Configurations

Navigate to config/environments/development.rb and add the following code.

config.hosts << /[a-z0-9]+\.ngrok\.io/

This will allow us to access our rails app from ngrok.
Navigate to config/initializers/cors.rb and add the following code or uncomment the existing code.

Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins '*'
    resource '*', headers: :any, methods: [:get, :post, :options]
  end
end

Be sure to replace origins 'example.com' with origins '*'if you uncomment existing code instead of adding the above code.

Environment variables

Inside the config folder create a file called local_env.yml and add the following code.

MPESA_CONSUMER_KEY: '<your consumer key>'
MPESA_CONSUMER_SECRET: '<your consumer secret>'
MPESA_PASSKEY: '<your passkey>'
MPESA_SHORTCODE: '174379'
MPESA_INITIATOR_NAME: 'testapi'
MPESA_INITIATOR_PASSWORD: '<your initiator password>'
CALLBACK_URL: '< your ngrok url>'
REGISTER_URL: "https://sandbox.safaricom.co.ke/mpesa/c2b/v1/registerurl"

** Note about the CALLBACK_URL **

To get you callback url first run your rails server rails s and copy the url from the terminal.
Then navigate to a new terminal and run ngrok http <port number> and replace with the port number from your rails server.
This will generate a url that you can use as your callback url.

In my case above ngrok http://127.0.0.1:3000 or ngrok http 3000 the url generated was https://5d5b-105-161-115-83.in.ngrok.io

Note that the url generated by ngrok changes every time you run it, so you will need to update your local_env.yml file with the new url every time you run ngrok.
Navigate to the ngrok url, you should see the page below, click on visit site which should take you to your rails app.

If you get a Blocked Host error, check these stackoverflow solutions.
In my case I had to replace config.hosts << /[a-z0-9]+\.ngrok\.io/ with config.hosts.clear in config/environments/development.rb. This however is not recommended for production. - Remember to add your local_env.yml file to your .gitignore file.

We need rails to load our environment variables, to do this add the following code to config/application.rb.

config.before_configuration do
  env_file = File.join(Rails.root, 'config', 'local_env.yml')
  YAML.load(File.open(env_file)).each do |key, value|
    ENV[key.to_s] = value
  end if File.exists?(env_file)
end

Wheeww!! That was a lot of configurations, let's now implement the code.

Implementing the code

First we need to write private methods to generate and get an access token from the Authorization API.
Generate Access Token Request -> Gives you a time bound access token to call allowed APIs in the sandbox.
Get Access Token -> Used to check if generate_acces_token_request is successful or not then it reads the responses and extracts the access token from the response and saves it to the database.
Add the following code to app/controllers/mpesa_controller.rb.
First require the rest-client gem require 'rest-client' then add the following code.

private

    def generate_access_token_request
        @url = "https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials"
        @consumer_key = ENV['MPESA_CONSUMER_KEY']
        @consumer_secret = ENV['MPESA_CONSUMER_SECRET']
        @userpass = Base64::strict_encode64("#{@consumer_key}:#{@consumer_secret}")
        headers = {
            Authorization: "Bearer #{@userpass}"
        }
        res = RestClient::Request.execute( url: @url, method: :get, headers: {
            Authorization: "Basic #{@userpass}"
        })
        res
    end

    def get_access_token
        res = generate_access_token_request()
        if res.code != 200
        r = generate_access_token_request()
        if res.code != 200
        raise MpesaError('Unable to generate access token')
        end
        end
        body = JSON.parse(res, { symbolize_names: true })
        token = body[:access_token]
        AccessToken.destroy_all()
        AccessToken.create!(token: token)
        token
    end

Stk Push Request

Under APIs -> M-pesa Express you can simulate a stk push request by selecting your app and changing Party A and Phone Number to your phone number.
Looking at the JSON the request body has the following parameters; { BusinessShortCode - The organization shortcode used to receive the transaction. Password - The password for encrypting the request.(Base64 encoded string,a combination of your BusinessShortCode, Passkey and Timestamp) Timestamp - The timestamp of the transaction in the format yyyymmddhhiiss TransactionType - The type of transaction (CustomerPayBillOnline or CustomerBuyGoodsOnline) Amount - The amount being transacted PartyA - The phone number sending the money. PartyB - The organization shortcode receiving the funds.Can be the same as the business shortcode. PhoneNumber - The mobile number to receive the STK push.Can be the same as Party A. CallBackURL - The url to where responses from M-Pesa will be sent to. Should be valid and secure. AccountReference - Value displayed to the customer in the STK Pin prompt message. TransactionDesc - A description of the transaction. }
You can read more on their documentation -> Lipa Na M-pesa Online API -> Request Parameter Definition.
Add the following code to app/controllers/mpesa_controller.rb.

 def stkpush
        phoneNumber = params[:phoneNumber]
        amount = params[:amount]
        url = "https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest"
        timestamp = "#{Time.now.strftime "%Y%m%d%H%M%S"}"
        business_short_code = ENV["MPESA_SHORTCODE"]
        password = Base64.strict_encode64("#{business_short_code}#{ENV["MPESA_PASSKEY"]}#{timestamp}")
        payload = {
        'BusinessShortCode': business_short_code,
        'Password': password,
        'Timestamp': timestamp,
        'TransactionType': "CustomerPayBillOnline",
        'Amount': amount,
        'PartyA': phoneNumber,
        'PartyB': business_short_code,
        'PhoneNumber': phoneNumber,
        'CallBackURL': "#{ENV["CALLBACK_URL"]}/callback_url",
        'AccountReference': 'Codearn',
        'TransactionDesc': "Payment for Codearn premium"
        }.to_json

        headers = {
        Content_type: 'application/json',
        Authorization: "Bearer #{get_access_token}"
        }

        response = RestClient::Request.new({
        method: :post,
        url: url,
        payload: payload,
        headers: headers
        }).execute do |response, request|
        case response.code
        when 500
        [ :error, JSON.parse(response.to_str) ]
        when 400
        [ :error, JSON.parse(response.to_str) ]
        when 200
        [ :success, JSON.parse(response.to_str) ]
        else
        fail "Invalid response #{response.to_str} received."
        end
        end
        render json: response
    end

Navigate to routes.rb and add the following code.

post 'stkpush', to: 'mpesas#stkpush'

Open postman and make a post request to your ngrok-url/stkpush with the following parameters.

{
    "phoneNumber": "2547xxxxxxxx",
    "amount": "1"
}

The request sents an STK push to the phone number provided.
Your response should look like this.

{
    "MerchantRequestID": "xxxx-xxxx-xxxx-xxxx",
    "CheckoutRequestID": "ws_CO_XXXXXXXXXXXXXXXXXXXXXXXXX",
    "ResponseCode": "0",
    "ResponseDescription": "Success. Request accepted for processing",
    "CustomerMessage": "Success. Request accepted for processing"
}

Save the CheckoutRequestID for the next step.

Stk Query Request

We can use the mpesa query to check if the payment was successful or not.
Under APIs -> M-pesa Express you can simulate a query a stk push request by selecting your app and inputing the CheckoutRequestID you got from the previous step.
The request body has the following parameters; { BusinessShortCode - The organization shortcode used to receive the transaction. Password - The password for encrypting the request.(Base64 encoded string,a combination of your BusinessShortCode, Passkey and Timestamp) Timestamp - The timestamp of the transaction in the format yyyymmddhhiiss CheckoutRequestID - The CheckoutRequestID used to identify the transaction on M-Pesa. }
Add the following code to app/controllers/mpesa_controller.rb.

def stkquery
        url = "https://sandbox.safaricom.co.ke/mpesa/stkpushquery/v1/query"
        timestamp = "#{Time.now.strftime "%Y%m%d%H%M%S"}"
        business_short_code = ENV["MPESA_SHORTCODE"]
        password = Base64.strict_encode64("#{business_short_code}#{ENV["MPESA_PASSKEY"]}#{timestamp}")
        payload = {
        'BusinessShortCode': business_short_code,
        'Password': password,
        'Timestamp': timestamp,
        'CheckoutRequestID': params[:checkoutRequestID]
        }.to_json

        headers = {
        Content_type: 'application/json',
        Authorization: "Bearer #{ get_access_token }"
        }

        response = RestClient::Request.new({
        method: :post,
        url: url,
        payload: payload,
        headers: headers
        }).execute do |response, request|
        case response.code
        when 500
        [ :error, JSON.parse(response.to_str) ]
        when 400
        [ :error, JSON.parse(response.to_str) ]
        when 200
        [ :success, JSON.parse(response.to_str) ]
        else
        fail "Invalid response #{response.to_str} received."
        end
        end
        render json: response
    end

Navigate to routes.rb and add the following code.

post 'stkquery', to: 'mpesas#stkquery'

Open postman and make a post request to your ngrok-url/stkquery with the following parameters.

{
    "checkoutRequestID": "ws_CO_XXXXXXXXXXXXXXXXXXXXXXXXX"
}

Your response should look like this.

[
    "success",
    {
        "ResponseCode": "0",
        "ResponseDescription": "The service request has been accepted successsfully",
        "MerchantRequestID": "8491-75014543-2",
        "CheckoutRequestID": "ws_CO_12122022094855872768372439",
        "ResultCode": "1032",
        "ResultDesc": "Request cancelled by user"
    }
]

You can use the ResultCode to check if the payment was successful or not.
Your mpesas_controller.rb should look like this.

class MpesasController < ApplicationController

    require 'rest-client'

    # stkpush
     def stkpush
        phoneNumber = params[:phoneNumber]
        amount = params[:amount]
        url = "https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest"
        timestamp = "#{Time.now.strftime "%Y%m%d%H%M%S"}"
        business_short_code = ENV["MPESA_SHORTCODE"]
        password = Base64.strict_encode64("#{business_short_code}#{ENV["MPESA_PASSKEY"]}#{timestamp}")
        payload = {
        'BusinessShortCode': business_short_code,
        'Password': password,
        'Timestamp': timestamp,
        'TransactionType': "CustomerPayBillOnline",
        'Amount': amount,
        'PartyA': phoneNumber,
        'PartyB': business_short_code,
        'PhoneNumber': phoneNumber,
        'CallBackURL': "#{ENV["CALLBACK_URL"]}/callback_url",
        'AccountReference': 'Codearn',
        'TransactionDesc': "Payment for Codearn premium"
        }.to_json

        headers = {
        Content_type: 'application/json',
        Authorization: "Bearer #{get_access_token}"
        }

        response = RestClient::Request.new({
        method: :post,
        url: url,
        payload: payload,
        headers: headers
        }).execute do |response, request|
        case response.code
        when 500
        [ :error, JSON.parse(response.to_str) ]
        when 400
        [ :error, JSON.parse(response.to_str) ]
        when 200
        [ :success, JSON.parse(response.to_str) ]
        else
        fail "Invalid response #{response.to_str} received."
        end
        end
        render json: response
    end

    # stkquery

    def stkquery
        url = "https://sandbox.safaricom.co.ke/mpesa/stkpushquery/v1/query"
        timestamp = "#{Time.now.strftime "%Y%m%d%H%M%S"}"
        business_short_code = ENV["MPESA_SHORTCODE"]
        password = Base64.strict_encode64("#{business_short_code}#{ENV["MPESA_PASSKEY"]}#{timestamp}")
        payload = {
        'BusinessShortCode': business_short_code,
        'Password': password,
        'Timestamp': timestamp,
        'CheckoutRequestID': params[:checkoutRequestID]
        }.to_json

        headers = {
        Content_type: 'application/json',
        Authorization: "Bearer #{ get_access_token }"
        }

        response = RestClient::Request.new({
        method: :post,
        url: url,
        payload: payload,
        headers: headers
        }).execute do |response, request|
        case response.code
        when 500
        [ :error, JSON.parse(response.to_str) ]
        when 400
        [ :error, JSON.parse(response.to_str) ]
        when 200
        [ :success, JSON.parse(response.to_str) ]
        else
        fail "Invalid response #{response.to_str} received."
        end
        end
        render json: response
    end

    private

    def generate_access_token_request
        @url = "https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials"
        @consumer_key = ENV['MPESA_CONSUMER_KEY']
        @consumer_secret = ENV['MPESA_CONSUMER_SECRET']
        @userpass = Base64::strict_encode64("#{@consumer_key}:#{@consumer_secret}")
        headers = {
            Authorization: "Bearer #{@userpass}"
        }
        res = RestClient::Request.execute( url: @url, method: :get, headers: {
            Authorization: "Basic #{@userpass}"
        })
        res
    end

    def get_access_token
        res = generate_access_token_request()
        if res.code != 200
        r = generate_access_token_request()
        if res.code != 200
        raise MpesaError('Unable to generate access token')
        end
        end
        body = JSON.parse(res, { symbolize_names: true })
        token = body[:access_token]
        AccessToken.destroy_all()
        AccessToken.create!(token: token)
        token
    end


end

Your routes.rb should look like this.

Rails.application.routes.draw do
    post 'stkpush', to: 'mpesas#stkpush'
    post 'stkquery', to: 'mpesas#stkquery'
end

I followed this tutorial and run into some errors and decided to write this article with some more clear steps.
The full code for this here.

I hope you found this helpful. If you have any questions, feel free to reach out to me on email: annetotoh@gmail.com.
THANK YOU!