Drew Harris for Rapyd

Posted on Jun 27 • Updated on Jul 19 • Originally published at community.rapyd.net

Payroll Payment Processing with Rapyd Disburse

#webdev #fintech #payments #nextjs

By: James Olaogun

Remote work is becoming the new norm, and businesses and their stakeholders now have the flexibility to operate from virtually any corner of the globe. However, this advancement comes with its challenges, such as effectively managing staff compensation and payroll, considering the diverse regulations and currencies in play across different locations. For example, have you ever wondered how platforms like remote.com solved this challenge and effortlessly continue to handle the payroll for their distributed workforce? The answer lies in cutting-edge technology, and one such awesome technology is the Rapyd Disburse API.

This article explores the world of payroll innovation and explains how to develop a basic payroll web application that can add an employee profile and set up their salary details. The article also demonstrates how to integrate the Rapyd Disburse API, a tool that empowers developers to create seamless payroll applications, into the payroll web application.

Implementing Payroll Payment Processing with Rapyd Disburse

The following diagram is an overview of the basic architecture of the payroll web application you're going to build.

The app has a user interface that displays the employee's profile, bank details, and salary and the employee status toggle. You'll develop the user interface using Next.js, a frontend technology framework. Additionally, you'll leverage the Next.js server API capability as the backend to handle the application logic and Rapyd Disburse API. Finally, there is the database, which will handle all relevant data storage. For simplicity, you can make use of the browser's local storage.

Prerequisites

To get started with the step-by-step instructions, kindly ensure you have the necessary prerequisites in place:

Next.Js: This tutorial uses Next.js and the browser's local storage as the database.
Rapyd Account: If you don't already have one, create an account on the Rapyd platform to access the Disburse API documentation and API keys.
NPM: Ensure you have NPM installed as you'll use it to install the necessary packages for the application.

Set Up a New Next.js Application

Let's get started by creating a new Next.js project. To do that, open your terminal, change the directory to your preferred directory, and run the following commands in your terminal:

npx create-next-app rapyd-basic-payroll-app && cd rapyd-basic-payroll-app

You should see a few prompts. Select the default option by punching the enter key command until the package starts downloading. After a successful download, you should get a response starting with "Success!", which indicates where the app was created and displays some other notices (new versions available, etc.).

Create the Necessary Pages and Components

The next step is to create the necessary components in the /src/components directory. To do that, head over to your terminal and run the following command:

mkdir src/components
touch src/components/Header.js
touch src/components/EmployeeForm.js
touch src/components/EmployeeStatusToggle.js

The command above creates the following files:

Header.js for a header view of the application
EmployeeForm.js for the employee profile form
EmployeeStatusToggle.js for the employee status toggle

You'll now create the necessary pages for routing in the /src/pages directory by running the following command in your terminal:

mkdir src/pages
touch src/pages/add-employee.js 
touch src/pages/list-employees.js

This command creates the following files:

add-employee.js for adding new employees
list-employees.js for listing all employees

Code the Components

You've now created some necessary frontend files, and you can start writing their code and styling them appropriately.

Starting with the Header.js component, copy and paste the following code snippet into the Header.js file to create the global header section of the application and style it:

import React from 'react';

const headerStyle = {
  backgroundColor: '#cacaca', 
  color: '#171717',           
  padding: '20px 0',  
  textAlign: 'center',  
};

const Header = () => {
  return (
    <header style={headerStyle}>
      <h1>Payroll Application</h1>
    </header>
  );
};

export default Header;

You'll now create and style the form that will be used to create employees. Copy and paste the following code snippet into the EmployeeForm.js file. The code snippet collects the employee's details and stores them in the local storage (see the comments within the code for more information):

import React, { useEffect, useState } from 'react';
import { useRouter } from 'next/router';

const EmployeeSalaryForm = () => {
  const router = useRouter();

  // List of countries for test purposes
  const countryCodes = [
    { code: 'US', name: 'United States (US)' },
    { code: 'GB', name: 'United Kingdom (GB)' },
    { code: 'PH', name: 'Philippines (PH)' },
    { code: 'CA', name: 'Canada (CA)' },
    { code: 'AU', name: 'Australia (AU)' },
    { code: 'DE', name: 'Germany (DE)' },
    { code: 'FR', name: 'France (FR)' },
    { code: 'JP', name: 'Japan (JP)' },
    { code: 'BR', name: 'Brazil (BR)' },
  ];

  // The form field data before submitting the form
  const [formData, setFormData] = useState({
    firstName: '',
    lastName: '',
    address: '',
    email: '',
    phoneNumber: '',
    countryCode: '',
    company: '',
    role: '',
    employmentDate: '',
    idCardType: '',
    idCardNumber: '',
    bankName: '',
    bankAccountNumber: '',
    salaryAmount: '',
    status: 'active',
  });

  const [AvailableBanks, setAvailableBanks] = useState([]);

  // Function to get the list of Rapyd-supported banks based on the selected country
  const getCountryCodeBanks = async (value) => {
    try {

        fetch('/api/get-banks', {
        method: 'POST',
        body: JSON.stringify({
          country: value,
        }),
        headers: {
          'Content-type': 'application/json; charset=UTF-8',
        }
        })
        .then((response) => response.json())
        .then((resJson) => {

          var resData = resJson.data.body.data

          var resDataArr = [];
          resData.forEach(eachData => {
            resDataArr.push({code: eachData.payout_method_type, name: eachData.name});
          });

          setAvailableBanks(resDataArr)

        });

      } catch (error) {
        console.error("Error in API route");
      }
  };

  // Function to update the form data when data is inputted into any of the fields
  const handleChange = (e) => {
    const { name, value } = e.target;
    setFormData({ ...formData, [name]: value });

    if (name == 'countryCode') {
        getCountryCodeBanks(value);
    }

  };

  // Function to handle form submit
  const handleSubmit = (e) => {
    e.preventDefault();

    // Retrieve existing employee data from localStorage
    const storedEmployeeData = JSON.parse(localStorage.getItem('employeeData')) || [];

    // Append the new employee data to the existing array
    const updatedEmployeeData = [...storedEmployeeData, formData];

    // Save the updated data back to localStorage
    localStorage.setItem('employeeData', JSON.stringify(updatedEmployeeData));

    // Clear the form after submission
    setFormData({
      firstName: '',
      lastName: '',
      address: '',
      email: '',
      phoneNumber: '',
      countryCode: '',
      company: '',
      role: '',
      employmentDate: '',
      idCardType: '',
      idCardNumber: '',
      bankName: '',
      bankAccountNumber: '',
      salaryAmount: '',
      status: 'active',
    });

    // Redirect the user to the employee listing page
    router.push('/list-employees');

    window.alert('Employee added successfully');
  };


  // Begin form styles
  const formContainerStyle = {
    maxWidth: '400px',
    margin: '0 auto',
    padding: '20px',
    border: '1px solid #ccc',
    borderRadius: '5px',
  };

  const inputStyle = {
    display: 'block',
    margin: '10px 0',
    padding: '5px',
    width: '100%',
  };

  const buttonStyle = {
    backgroundColor: '#007bff',
    color: 'white',
    border: 'none',
    padding: '10px 20px',
    margin: '20px 0',
    cursor: 'pointer',
  };
  // End form styles


  //Form fields
  return (
    <div style={formContainerStyle}>
        <form onSubmit={handleSubmit}>
        <label>
            First Name:
            <input
            type="text"
            name="firstName"
            value={formData.firstName}
            onChange={handleChange}
            style={inputStyle}
            />
        </label>
        <label>
            Last Name:
            <input
            type="text"
            name="lastName"
            value={formData.lastName}
            onChange={handleChange}
            style={inputStyle}
            />
        </label>
        <label>
            Full Address:
            <input
            type="text"
            name="address"
            value={formData.address}
            onChange={handleChange}
            style={inputStyle}
            />
        </label>
        <label>
            Email:
            <input
            type="email"
            name="email"
            value={formData.email}
            onChange={handleChange}
            style={inputStyle}
            />
        </label>
        <label>
            Phone Number:
            <input
            type="text"
            name="phoneNumber"
            value={formData.phoneNumber}
            onChange={handleChange}
            style={inputStyle}
            />
        </label>
        <label>
            Country Code:
            <select
            name="countryCode"
            value={formData.countryCode}
            onChange={handleChange}
            style={inputStyle}
            >
            <option value="">Select Country Code</option>
            {countryCodes.map((country, index) => (
                <option key={index} value={country.code}>
                {country.name}
                </option>
            ))}
            </select>
        </label>
        <label>
            Company:
            <input
            type="text"
            name="company"
            value={formData.company}
            onChange={handleChange}
            style={inputStyle}
            />
        </label>
        <label>
            Role:
            <input
            type="text"
            name="role"
            value={formData.role}
            onChange={handleChange}
            style={inputStyle}
            />
        </label>
        <label>
            Employment Date:
            <input
            type="date"
            name="employmentDate"
            value={formData.employmentDate}
            onChange={handleChange}
            style={inputStyle}
            />
        </label>
        <label>
            Identification Card Type:
            <select
            name="idCardType"
            value={formData.idCardType}
            onChange={handleChange}
            style={inputStyle}
          >
            <option value="">Select ID Type</option>
            <option value="social_security">Social Security</option>
            <option value="work_permit">Work Permit</option>
            <option value="international_passport">International Passport</option>
            <option value="residence_permit">Residence Permit</option>
            <option value="company_registered_number">company Registered Number</option>
          </select>
        </label>
        <label>
            Identification Card Number:
            <input
            type="text"
            name="idCardNumber"
            value={formData.idCardNumber}
            onChange={handleChange}
            style={inputStyle}
            />
        </label>
        <label>
            Bank:
            <select
            name="bankName"
            value={formData.bankName}
            onChange={handleChange}
            style={inputStyle}
          >
            <option value="">Select Bank</option>
            {AvailableBanks.map((bank, index) => (
                <option key={index} value={bank.code}>
                {bank.name}
                </option>
            ))}
            {/* Get the list of available banks in the selected country from Rapyd */}
          </select>
        </label>
        <label>
            Bank Account Number:
            <input
            type="text"
            name="bankAccountNumber"
            value={formData.bankAccountNumber}
            onChange={handleChange}
            style={inputStyle}
            />
        </label>
        <label>
            Salary Amount:
            <input
            type="text"
            name="salaryAmount"
            value={formData.salaryAmount}
            onChange={handleChange}
            style={inputStyle}
            />
        </label>
        <button type="submit" style={buttonStyle}>Submit</button>
        </form>
    </div>
  );
};

export default EmployeeSalaryForm;

Finally, in the components folder, copy and paste the following code snippet into the EmployeeStatusToggle.js component, which manages the enable and disable feature of the application:

import React, { useState } from 'react';

const EmployeeStatusToggle = ({ initialStatus, onToggle }) => {
  const [status, setStatus] = useState(initialStatus);

  const toggleStyle = {
    display: 'inline-block',
    position: 'relative',
    width: '40px',
    height: '20px',
    cursor: 'pointer',
    backgroundColor: 'lightgrey',
    borderRadius: '10px',
  };

  const switchStyle = {
    position: 'absolute',
    width: '20px',
    height: '20px',
    borderRadius: '50%',
    transition: 'background-color 0.3s ease',
  };

  const activeSwitchStyle = {
    ...switchStyle,
    left: '0',
    backgroundColor: '#2ecc71', // Green for active status
  };

  const inactiveSwitchStyle = {
    ...switchStyle,
    left: '20px',
    backgroundColor: '#e74c3c', // Red for inactive status
  };

  const handleToggle = () => {
    const newStatus = status === 'active' ? 'inactive' : 'active';
    setStatus(newStatus);
    onToggle(newStatus);
  };

  return (
    <label style={toggleStyle} className="employee-status-toggle">
      <span
        style={status === 'active' ? activeSwitchStyle : inactiveSwitchStyle}
        onClick={handleToggle}
      ></span>
    </label>
  );
};

export default EmployeeStatusToggle;

Code the Pages

With the components coded, you can proceed to code the created pages. Each page will import its respective components accordingly and display them on the browser. Also, note that the name of each page is the web route to access the page on the browser.

Start by copying and pasting the following code into the file add-employee.js to import EmployeeForm.js and Header.js:

import React from 'react';
import '../app/globals.css'
import Header from '../components/Header';
import EmployeeForm from '../components/EmployeeForm';

const AddEmployee = () => {

  const containerStyle = {
    textAlign: 'center'
  };

  return (
    <div style={containerStyle}>
      <Header />
      <h2>Add Employee</h2>
      <EmployeeForm />
    </div>
  );
};

export default AddEmployee;

Copy and paste the following code snippet into the list-employees.js file to import the Header.js and EmployeeStatusToggle.js components and a table element that displays all the created employees:

import React, { useEffect, useState } from 'react';
import Header from '../components/Header';
import EmployeeStatusToggle from '../components/EmployeeStatusToggle';

const ListEmployees = () => {
  const [employeeData, setEmployeeData] = useState([]);

  useEffect(() => {
    // Retrieve employee data from localStorage on component mount
    const storedEmployeeData = JSON.parse(localStorage.getItem('employeeData')) || [];
    setEmployeeData(storedEmployeeData);
  }, []);

  const handleStatusToggle = (index, newStatus) => {
    // Update the status of the employee at the specified index
    const updatedEmployeeData = [...employeeData];
    updatedEmployeeData[index].status = newStatus;
    setEmployeeData(updatedEmployeeData);

    // Update the data in localStorage
    localStorage.setItem('employeeData', JSON.stringify(updatedEmployeeData));
  };

  const containerStyle = {
    textAlign: 'center'
  };

  const tableStyle = {
    borderCollapse: 'collapse',
    width: '100%',
    marginTop: '20px',
  };

  const thStyle = {
    backgroundColor: '#cacaca',
    color: '#171717',
    padding: '10px',
    textAlign: 'center',
  };

  const tdStyle = {
    border: '1px solid #ccc',  
    padding: '10px',
    textAlign: 'left',
  };


  return (
    <div style={containerStyle}>
      <Header />
      <h2>List of Employees</h2>
      <table style={tableStyle}>
        <thead>
          <tr>
            <th style={thStyle}>Name</th>
            <th style={thStyle}>Email</th>
            <th style={thStyle}>Phone</th>
            <th style={thStyle}>Country Code</th>
            <th style={thStyle}>Company</th>
            <th style={thStyle}>Role</th>
            <th style={thStyle}>Employment Date</th>
            <th style={thStyle}>ID Card Type</th>
            <th style={thStyle}>ID Card Number</th>
            <th style={thStyle}>Bank Name</th>
            <th style={thStyle}>Bank Account Number</th>
            <th style={thStyle}>Salary Amount</th>
            <th style={thStyle}>Status</th>
          </tr>
        </thead>
        <tbody>
          {employeeData.map((employee, index) => (
            <tr key={index}>
              <td style={tdStyle}>{employee.firstName} {employee.lastName}</td>
              <td style={tdStyle}>{employee.email}</td>
              <td style={tdStyle}>{employee.phoneNumber}</td>
              <td style={tdStyle}>{employee.countryCode}</td>
              <td style={tdStyle}>{employee.company}</td>
              <td style={tdStyle}>{employee.role}</td>
              <td style={tdStyle}>{employee.employmentDate}</td>
              <td style={tdStyle}>{employee.idCardType}</td>
              <td style={tdStyle}>{employee.idCardNumber}</td>
              <td style={tdStyle}>{employee.bankName}</td>
              <td style={tdStyle}>{employee.bankAccountNumber}</td>
              <td style={tdStyle}>{employee.salaryAmount}</td>
              <td style={tdStyle}>
                <EmployeeStatusToggle
                  initialStatus={employee.status}
                  onToggle={(newStatus) => handleStatusToggle(index, newStatus)}
                />  
              </td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
};

export default ListEmployees;

After adding the code snippet, go to src/app/globals.css and src/app/page.module.css. Replace all the CSS styles that came with the Next.js installation with the following CSS:

body{
  margin: 0px;
}

You also need to replace the default src/app/page.js code with the following snippet, which creates the landing page of the application that routes the users to the "Add Employee" and "List Employees" pages:

import React from 'react';
import Header from '../components/Header';

const Home = () => {
  const containerStyle = {
    textAlign: 'center'
  };

  const actionUrlsStyle = {
    listStyle: 'none', 
    padding: 0, 
    display: 'flex', 
    justifyContent: 'center',
  };

  const actionUrlItemStyle = {
    margin: '0 10px', 
  };

  return (
    <div style={containerStyle}>
      <Header />
      <h2>Welcome</h2>
      <h3> Use the navigation below to add or view employees</h3>
      <ul style={actionUrlsStyle} className="action-urls">
        <li style={actionUrlItemStyle} className="action-url-item">
          <a href={`/add-employee`}>Add Employee</a>
        </li>
        <li style={actionUrlItemStyle} className="action-url-item">
          <a href={`/list-employees`}>List Employees</a>
        </li>
      </ul>
    </div>
  );
};

export default Home;

Before moving on to the next step, you also need to create a helper file that will contain the list of currency codes and their corresponding country code. This helper file will help you automatically determine the payout currency based on the selected beneficiary country.

Change the directory to /src and create a new directory there called utilities using the following command:

mkdir utilities

Then, create a new file called currencyCodes.js in the /utilities directory using the following command:

touch currencyCodes.js

Copy the code snippet below into the newly created currencyCodes.js:

const CurrencyCodes = [
    { code: 'USD', country_code: 'US' },
    { code: 'GBP', country_code: 'GB' },
    { code: 'PHP', country_code: 'PH' },
    { code: 'CAD', country_code: 'CA' },
    { code: 'AUD', country_code: 'AU' },
    { code: 'EUR', country_code: 'DE' },
    { code: 'JPY', country_code: 'JP' },
    { code: 'BRL', country_code: 'BR' }
  ];

  export { CurrencyCodes };

Retrieve Your Rapyd API Keys

At this point, you are done creating and styling the pages for the application. The final steps involve integrating the Rapyd Disburse API into the app. Before working with the API, you'll need your API keys. To locate them, log in to the Rapyd dashboard with your login details.

Once you're logged in, click the Developers link on the sidebar, and you should be routed to the Rapyd Credential Details page. You will see your access and secret key. Copy both keys and save them in a safe place; you will need them in the later part of this tutorial.

Integrate the Rapyd Disburse API (Set Up Base Functions)

The next step is to create another helper file for the functions that set up the Rapyd signature and header data. To do that, change the directory to the /utilities and create a file called rapyd.js using the following command:

cd /path/to/app/src/utilities
touch rapyd.js

Copy and paste the code snippet below into the newly created rapyd.js file, replacing {{YOUR_SECRET_KEY}} and {{YOUR_ACCESS_KEY}} with your Rapyd secret key and access key to generate the required header, salt, and signature (see the comments within the code for more information about what's happening):

import https from 'https';
import crypto from 'crypto';

const secretKey = "{{YOUR_SECRET_KEY}}";
const accessKey = "{{YOUR_ACCESS_KEY}}";

const log = false;

async function makeRequest(method, urlPath, body = null) {
  try {
    const httpMethod = method; // get|put|post|delete - must be lowercase.
    const httpBaseURL = "sandboxapi.rapyd.net";
    const httpURLPath = urlPath; // Portion after the base URL.
    const salt = generateRandomString(8); // Randomly generated for each request.
    const idempotency = new Date().getTime().toString();
    const timestamp = Math.round(new Date().getTime() / 1000); // Current Unix time (seconds).
    const signature = sign(httpMethod, httpURLPath, salt, timestamp, body);

    const options = {
      hostname: httpBaseURL,
      port: 443,
      path: httpURLPath,
      method: httpMethod,
      headers: {
        'Content-Type': 'application/json',
        access_key: accessKey,
        salt: salt,
        timestamp: timestamp,
        signature: signature,
        idempotency: idempotency,
      },
    };

    return await httpRequest(options, body, log);
  } catch (error) {
    console.error("Error generating request options", error);
    throw error;
  }
}

function sign(method, urlPath, salt, timestamp, body) {
  try {
    let bodyString = "";
    if (body) {
      bodyString = JSON.stringify(body); // Stringified JSON without whitespace.
      bodyString = bodyString == "{}" ? "" : bodyString;
    }

    let toSign =
      method.toLowerCase() +
      urlPath +
      salt +
      timestamp +
      accessKey +
      secretKey +
      bodyString;
    log && console.log(`toSign: ${toSign}`);

    let hash = crypto.createHmac('sha256', secretKey);
    hash.update(toSign);
    const signature = Buffer.from(hash.digest("hex")).toString("base64");
    log && console.log(`signature: ${signature}`);

    return signature;
  } catch (error) {
    console.error("Error generating signature");
    throw error;
  }
}

function generateRandomString(size) {
  try {
    return crypto.randomBytes(size).toString('hex');
  } catch (error) {
    console.error("Error generating salt");
    throw error;
  }
}

async function httpRequest(options, body) {
  return new Promise((resolve, reject) => {
    try {
      let bodyString = "";
      if (body) {
        bodyString = JSON.stringify(body);
        bodyString = bodyString == "{}" ? "" : bodyString;
      }

      log && console.log(`httpRequest options: ${JSON.stringify(options)}`);
      const req = https.request(options, (res) => {
        let response = {
          statusCode: res.statusCode,
          headers: res.headers,
          body: '',
        };

        res.on('data', (data) => {
          response.body += data;
        });

        res.on('end', () => {
          response.body = response.body ? JSON.parse(response.body) : {};
          log && console.log(`httpRequest response: ${JSON.stringify(response)}`);

          if (response.statusCode !== 200) {
            return reject(response);
          }

          return resolve(response);
        });
      });

      req.on('error', (error) => {
        return reject(error);
      });

      req.write(bodyString);
      req.end();
    } catch (err) {
      return reject(err);
    }
  });
}

export { makeRequest };

This snippet also contains the generic HTTP functions that help consume all API endpoints. All you have to do to consume any API endpoint is pass the API endpoint URL, method, and payload into the function.

It's always best practice to add your {{YOUR_SECRET_KEY}} and {{YOUR_ACCESS_KEY}} via environment variables, especially when integrating into real-world applications.

Integrate the Payout Method Types API

Before you can send out the payment, you need to check that the employee's bank is supported by Rapyd. You can do this by confirming which payout methods are available in their country when adding employees.

To do that, you first need to create the /api route by changing the directory and creating the /api directory using the following command:

cd /path/to/app/src/pages
mkdir api

Create a new file called get-banks.js using the touch get-banks.js command. Then, copy and paste the code snippet below into this file to allow it to consume the Payout Method Types API:

import { makeRequest } from '../../utilities/rapyd.js'; // Import Rapyd base functions
import {CurrencyCodes} from '../../utilities/currencyCodes.js' // Import currency and country codes

export default async function handler(req, res) { //Function to handle Next.js request

  const country = req.body.country;
  var currency

  // Get the selected country currency code
  CurrencyCodes.forEach(curcode => {
    if (curcode.country_code == country) {
      currency = curcode.code;
    }
  });

  // Set the Rapyd API URL
  const url = '/v1/payouts/supported_types?category=bank&beneficiary_country='+country+'&payout_currency='+currency;

  //Make the API request to Rapyd
  const response = await makeRequest('get', url, {});

  // Return the request response
  res.status(200).json({ data: response })

}

Generate, Fund, and Retrieve Rapyd E-wallet ID

The Rapyd e-wallet can be created via your Rapyd Client Portal or API. In this tutorial, you'll use the API method to create the e-wallet.

Change the directory to /api using the following command:

cd /path/to/app/src/page/api

Use the touch create-wallet.js command to create a new file called create-wallet.js. Then, copy and paste the following code snippet into the file so it can consume the Create Wallet API (make sure you fill in all the relevant details in the placeholders):

import { makeRequest } from '../../utilities/rapyd.js'; // Import Rapyd base functions

export default async function handler(req, res) { //Function to handle Next.js request

    const body = {
        first_name: '{{Your First Name}}', //Your First Name
        last_name: '{{Your Last Name}}', //Your Last Name
        ewallet_reference_id: '{{Your Preferred Ref ID}}', //Your Preferred Ref ID
        metadata: {
          merchant_defined: true
        },
        type: 'company',
        contact: {
          phone_number: '{{Your Phone Number}}', //Your Phone Number
          email: '{{Your Email}}', //Your Email
          first_name: '{{Your First Name}}', //Your First Name
          last_name: '{{Your Last Name}}', // Your Last Name
          mothers_name: '{{Your Mothers Name}}', // Your Mother's Name
          contact_type: 'business',
          address: { //Your Address
            name: '{{Name}}',
            line_1: '{{Line 1}}',
            line_2: '',
            line_3: '',
            city: '{{City}}',
            state: '{{Sate}}',
            country: '{{Country}}',
            zip: '{{Zip}}',
            phone_number: '{{Phone}}',
            metadata: { number: 2 },
            canton: '',
            district: ''
          },
          identification_type: '{{Your Identification Type}}', //Your Identification Type e.g "PA",
          identification_number: '{{Your Identification Number}}', //Your Identification Number e.g "1234567890"
          date_of_birth: '{{Your Date of Birth}}', //Your Date of Birth
          country: '{{Your Country}}', // Your Country
          metadata: {
            merchant_defined: true
          },
          business_details: {
            entity_type: 'association',
            name: "{{Your Company Name}}", //Your Company Name
            registration_number: "{{Your company registration number}}", //Your company registration number
            industry_category: 'company',
            industry_sub_category: "{{Your business category}}", //Your business category
            address: { //Your Address
                name: '{{Name}}',
                line_1: '{{Line 1}}',
                line_2: '',
                line_3: '',
                city: '{{City}}',
                state: '{{Sate}}',
                country: '{{Country}}',
                zip: '{{Zip}}',
                phone_number: '{{Phone}}',
                metadata: {
                    merchant_defined: true
                }
            }
          }
        }
    };



  // Set the Rapyd API URL
  const url = '/v1/user';

  //Make the API request to Rapyd
  const response = await makeRequest('POST', url, body);

  // Return the request response
  res.status(200).json({ data: response })

}

Using touch fund-wallet.js, create a new file called fund-wallet.js. Copy and paste in the following code to fund the wallet you just created with a fixed amount, where {{YOUR WALLET ID}} is the ID of the wallet you just created:

import { makeRequest } from '../../utilities/rapyd.js'; // Import Rapyd base functions

export default async function handler(req, res) { //Function to handle Next.js request

  const data = {
    "amount": 500000, //fixed amount of 500,000
    "currency": "USD",
    "ewallet": "{{YOUR WALLET ID}}",
    "metadata": {
        "merchant_defined": true
    }
  }

  const url = '/v1/account/deposit'

  const response = await makeRequest('POST', url, data);

  // Return the request response
  res.status(200).json({ data: response })

}

Change the directory to /components using the following command:

cd /path/to/app/src/components

Create a new file called WalletDetails.js using the touch WalletDetails.js command. Then, copy and paste in the following code snippet, which shows the e-wallet ID if one exists or presents a call to action to create an e-wallet when clicked if one doesn't:

import React, { useState, useEffect } from 'react';

const style = {
    cursor: 'pointer', 
    color: '#2525aa',
}

const WalletDetails = () => {

    const [WalletID, setWalletID] = useState("");

    useEffect(() => {
        const WalletIDLSDAta = localStorage.getItem('WalletID') || "";
        setWalletID(WalletIDLSDAta);
    }, []);

    // Function to generate wallet ID
    const generateWalletId = async () => { 

        try {

            fetch('/api/create-wallet', {
            method: 'GET',
            headers: {
              'Content-type': 'application/json; charset=UTF-8',
            }
            })
            .then((response) => response.json())
            .then((resJson) => {

              var resData = resJson.data.body.data.id

              setWalletID(resData);
              localStorage.setItem('WalletID', resData);

            });

          } catch (error) {
            console.error("Error in API route");
          }

    };

     // Fund wallet with a fixed amount
     const fundWallet = async () => { 

      try {

          fetch('/api/fund-wallet', {
          method: 'GET',
          headers: {
            'Content-type': 'application/json; charset=UTF-8',
          }
          })
          .then((response) => response.json())
          .then((resJson) => {

            alert("Fixed amount added successfully")

          });

        } catch (error) {
          console.error("Error in API route");
        }

  };

    return (
    <div>
       {WalletID == "" ? 
       <small onClick={generateWalletId} style={style}>Generate Wallet ID</small> : 
       <div>
        <small>{WalletID}</small>
          <br></br>
        <small onClick={fundWallet} style={style}>Fund Wallet</small>
       </div>

       }
    </div>
    );
};

export default WalletDetails;

Integrate the Rapyd Payouts APIs (Create Payout, Confirm Payout, and Complete Payout)

You'll now add the necessary code to consume the Rapyd Payouts APIs and ensure a successful payout. The Create Payout endpoint initiates a payout request. If the payout request is between multiple currencies, it will require that you confirm the foreign exchange by consuming the Confirm Payout endpoint. Once it has been done and the payout has a status of "Created", you can proceed to consume the Complete Payout endpoint to finalize the payout.

Start by changing the directory to /api directory using the following command:

cd /path/to/app/src/page/api

Afterward, use touch request-payout.js to create a new file called request-payout.js. Then, copy and paste the following snippet into the file so it can consume the Create Payout API:

import { makeRequest } from '../../utilities/rapyd.js'; // Import Rapyd base functions
import {CurrencyCodes} from '../../utilities/currencyCodes.js' // Import currency and country codes

export default async function handler(req, res) { //Function to handle Next.js request

    var payout_currency

    // Get the selected country currency code
    CurrencyCodes.forEach(curcode => {
      if (curcode.country_code == req.body.country) {
          payout_currency = curcode.code;
      }
    });


    const body = {
      "beneficiary": {
          "payment_type": "regular",
          "address": "1 Main Street", //beneficiary Address
          "city": "Anytown", //beneficiary City
          "country": req.body.country, //beneficiary Country Code
          "first_name": req.body.first_name,
          "last_name": req.body.last_name,
          "state": "NY", //beneficiary State
          "postcode": "10101", //beneficiary Postcode
          "aba": "573675777", //for US bank account
          "iban": "DE75512108001245126199", //Customer Iban
          "account_number": req.body.account_number, 
          "identification_type": req.body.identification_type,
          "identification_value": req.body.identification_value,
          "phone_number": req.body.phone_number,
      },
      "beneficiary_country": req.body.country,
      "beneficiary_entity_type": "individual",
      "description": "Salary payout - wallet to bank account", //Your Secription
      "payout_method_type": req.body.bank,
      "ewallet": "ewallet_8ce9f7a26b296c98ed2ee32028bead0a", //Your Wallet ID
      "metadata": {
          "merchant_defined": true
      },
      "payout_amount": req.body.amount,
      "payout_currency": payout_currency,
      "confirm_automatically": "true",
      "sender": {
          "first_name": "John", //Your first name
          "last_name": "Doe", // Yout last name
          "identification_type": "work_permit", //Your ID Type
          "identification_value": "asdasd123123", //Your ID number
          "phone_number": "19019019011", //Your phone number
          "occupation": "professional", //Your occupation
          "source_of_income": "business",
          "date_of_birth": "11/12/1913", //Your DOB
          "address": "1 Main Street", //Your Address
          "postcode": "12345", //Your Postcode
          "country": "US",
          "city": "Anytown",//Your City
          "state": "NY",//Your State
          "purpose_code": "investment_income",
          "beneficiary_relationship": "employee"
      },
      "sender_country": "US", //Your Country
      "sender_currency": "USD", //Your Currency
      "sender_entity_type": "individual",
      "statement_descriptor": "Salary payout" //Unstructured remittance information
  }

  // Set the Rapyd API URL
  const url = '/v1/payouts';

  //Make the API request to Rapyd
  const response = await makeRequest('POST', url, body);

  // Return the request response
  res.status(200).json({ data: response })

}

Next, create a new file called confirm-payout.js using the touch confirm-payout.js command. Copy and paste the code snippet below to the file to allow it to consume the Confirm Payout API:

import { makeRequest } from '../../utilities/rapyd.js'; // Import Rapyd base functions

export default async function handler(req, res) { //Function to handle Next.js request

  // Set the Rapyd API URL
  const payoutID = req.body.payoutID;

  const url = '/v1/payouts/confirm/'+payoutID; 


  //Make the API request to Rapyd
  const response = await makeRequest('POST', url, {});

  // Return the request response
  res.status(200).json({ data: response })

}

Lastly, create a new file called complete-payout.js using the touch complete-payout.js command. Copy and paste the code snippet below into the file to allow it to consume the Complete Payout API:

import { makeRequest } from '../../utilities/rapyd.js'; // Import Rapyd base functions

export default async function handler(req, res) { //Function to handle Next.js request

  // Set the Rapyd API URL
  const payoutID = req.body.payoutID;
  const amount = req.body.amount

  const url = '/v1/payouts/complete/'+payoutID+'/'+amount; 


  //Make the API request to Rapyd
  const response = await makeRequest('POST', url, {});

  // Return the request response
  res.status(200).json({ data: response })

}

You could alternatively use the Complete Payout webhook to complete the payment, but for the purpose of simplicity, this tutorial uses only the API.

Go back to /pages/list-employees.js and import code snippet below the EmployeeStatusToggle import :

import WalletDetails from '../components/WalletDetails';
import PayOut from '../components/PayOut';

Add <WalletDetails /> to the line after the <h2> tag. Additionally, add a new table head and body for the PayOut action using the code snippet below:

<th style={thStyle}>Action</th>

<td style={tdStyle}>
                <PayOut
                  employee={employee}
                />  
</td>

You then need to create the PayOut component. Change to the component directory cd /path/to/app/src/components and use touch PayOut.js to create a new file. Copy and paste the code snippet below into the file to enable the functions that trigger the payout API files you coded in the previous paragraph:

import React, { useState } from 'react';

const PayOut = ({ employee }) => {

    const style = {
        backgroundColor: '#007BFF',
        color: '#FFFFFF',
        padding: '10px 20px',
        border: 'none',
        borderRadius: '5px',
        cursor: 'pointer',
        fontSize: '16px'
      }

    const [payoutText, setPayoutText] = useState("Payout");

    // Function to confirm FX and complete payout
    const CompletePayout = async (resData) => { 

      try {

          fetch('/api/complete-payout', {
          method: 'POST',
          body: JSON.stringify({
              payoutID: resData.id,
              amount: resData.sender_amount,
          }),
          headers: {
            'Content-type': 'application/json; charset=UTF-8',
          }
          })
          .then((response) => response.json())
          .then((resJson) => {

            var resData = resJson.data.body

            console.log("complete-payout", resData)

            setPayoutText("Paid")

          });

      } catch (error) {
          console.error("Error in API route");
      }

    };


    // Function to confirm FX and complete payout
    const confirmFXandCompletePayout = async (resData) => { 

      try {

          fetch('/api/confirm-payout', {
          method: 'POST',
          body: JSON.stringify({
              payoutID: resData.id,
          }),
          headers: {
            'Content-type': 'application/json; charset=UTF-8',
          }
          })
          .then((response) => response.json())
          .then((resJson) => {

            var confirmResData = resJson.data.body.data

            CompletePayout(confirmResData)

            console.log("confirmed-fx", confirmResData)

          });

      } catch (error) {
          console.error("Error in API route");
      }

    };


    const handleClick = () => {
        setPayoutText("Paying...")

        try {

            fetch('/api/request-payout', {
            method: 'POST',
            body: JSON.stringify({
              country: employee.countryCode,
              bank: employee.bankName,
              amount: employee.salaryAmount,
              first_name: employee.firstName,
              last_name: employee.lastName,
              account_number: employee.bankAccountNumber,
              identification_type: employee.idCardType,
              identification_value: employee.idCardNumber,
              phone_number: employee.phoneNumber,

            }),
            headers: {
              'Content-type': 'application/json; charset=UTF-8',
            }
            })
            .then((response) => response.json())
            .then((resJson) => {

              var resData = resJson.data.body.data

              switch (resData.status) {
                case "Confirmation":
                  condirmFXandCompletePayout(resData)
                  break;
                case "Created":
                  CompletePayout(resData)
                  break;
                case "Hold":
                  setPayoutText("Hold")
                  break;
                case "Expired":
                  setPayoutText("Expired")
                  break;
                case "Pending":
                  setPayoutText("Pending")
                  break;
                case "Canceled":
                  setPayoutText("Canceled")
                  break;
                case "Completed":
                  setPayoutText("Paid")
                  break;
                case "Declined":
                  setPayoutText("Declined")
                  break;
                case "Error":
                  setPayoutText("Error")
                  break;
                default:
                  setPayoutText("Error")
                  break;
              }

              console.log("request-payout", resData)

            });

        } catch (error) {
            console.error("Error in API route");
        }

    };

  return (
    <div>
        <button style={style} onClick={handleClick}>{payoutText}</button>
    </div>
  );
};

export default PayOut;

Test the Application

Now that you've created all the necessary components and pages and integrated the Rapyd APIs, it's time to demo the application. Start by running the application with the npm run dev command. You should see a response like the screenshot below.

You should also see the server URL. In the example, it's http://localhost:3000. Visit the URL and you should see a "Payroll Application" page.

Click Add Employee to add a new employee.

When you are done filling out the form, click Submit and you'll see an alert indicating that an employee was added successfully.

After you acknowledge the alert, you will be redirected to the "List of Employees" page.

Go back to the "Add Employee" page and add another employee.

You can now try generating and funding a wallet. You can create as many wallets as necessary for the complexity of your application. However, for the purpose of this tutorial, you will be creating and using only one wallet.

Click Generate Wallet ID under the "List of Employees" header to create your wallet. After the wallet has been created successfully, you should see the wallet ID and a link to fund the wallet.

Fund the wallet with a fixed amount of US$500,000 by clicking Fund Wallet. You should see an alert saying "Fixed amount added successfully".

Finally, try paying the two employees by clicking Payout on the right side of the table. When the payout function is processed, the text should change to "Paying…", and it will change to "Paid" when the payout is completed. Also, note that it can show a different status, such as "Hold", "Expired", or "Declined", depending on the bank option that was selected during employee creation. See the official documentation for the list of the status and their meaning. To simulate a successful transaction, for Germany, you can select Eurozone SEPA payout, and for the Philippines, you can select Bank Transfer to ANZ Bank in the Philippines.

Conclusion

This article provided a brief introduction to Rapyd's Disburse API and a step-by-step tutorial for incorporating them into a simple payroll application using Next.js. You can view your payout history and transactions, switch between the production and sandbox environments, and more through your Client Portal. The complete code for this tutorial is also available on GitHub.

Rapyd offers a robust and reliable payment gateway solution that is fast and secure for both local and international business transactions. It supports more than nine hundred payment options and more than sixty-five currencies from different countries. Simply register on the Client Portal and follow the Get Started guide to start your integration.

DEV Community