DEV Community: xunylpay

Integrating PayMongo API in Next.js - Part 2

xunylpay — Mon, 03 Jan 2022 05:34:09 +0000

Hi there,

In this two part article, I'll be guiding you on how to integrate the PayMongo API in NextJS

In Part 1, we have a brief discussion on PayMongo payment workflows and how to setup credit card payments.

In Part 2, we tackle using webhooks to monitor payments and we move forward to processing GrabPay and GCash Payments.

Introduction
- Demo
- Webhooks
Let's Code
- Setting Up
- Running the project
- Creating an endpoint for the webhook
- Creating the webhook
- Testing the webhook
- Accepting E-wallet Payments (GCash and GrabPay)
  - Create a source
  - Have the customer authorize the payment
  - Create a Payment using the chargeable Source
Conclusion

Introduction

This is a simple guide for developers to integrate the PayMongo API in NextJS. Here, we'll start with a simple checkout and payment template project, and then move forward by filling up the API calls necessary to process payments.

PayMongo provides businesses an easy, user-friendly way to accept payments from their customers. It is a payment gateway that process Visa/Mastercard, GCash, and GrabPay payments.

PayMongo API is for those who want to directly integrate their site or app with PayMongo. Using the API allows you to take full control of the user's experience and integrate the payments directly with your systems and databases.

ngrok is a free service that helps you share a site or server running on your local machine

Demo

Live Preview: https://nextjs-paymongo-api.vercel.app/
GitHub: https://github.com/xunylpay/nextjs-paymongo-api

Webhooks

PayMongo provides webhooks that notify you of events happening during the payment process. Webhooks are a sure fire way to track payments especially if you want to store payment statuses in the database. Listening to events in the front end may result to consistency/reliability issues in your system (eg. client connection is cut, client closes the window after payment).

Let's Code

Setting Up

In setting up, we assume that you have already finished doing the first part of this tutorial. Feel free to download or clone the part-1-done branch in the repository.

If you have not done so, create a .env file on the root folder. Insert your public and secret keys in this format:

NEXT_PUBLIC_PAYMONGO_PUBLIC=pk_test_xxxxxxxxxxxxxxxxxxxxxxxx
PAYMONGO_SECRET=sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

The NEXT_PUBLIC_ is important when exposing the environment variable in the front end

We also need ngrok to test our webhook endpoint locally.

yarn add ngrok --dev

Let's also set up our package.json script so we can start our ngrok tunnel.
package.json

"scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "ngrok": "ngrok http 3000"
 },

Running the project

Now open the project in your favorite text editor or IDE (Integrated Development Environment). Open a terminal then run the following commands to start up the development server.

yarn
yarn dev

On localhost:3000 you should be seeing this:

On a different terminal, let's start our ngrok tunnel.

yarn ngrok

or

ngrok http 3000

On your terminal, you should be seeing something like this:

Take note of your forwarding address. In the case above, it is https://0f99-136-158-3-235.ngrok.io

Creating an endpoint for the webhook

We need to create an endpoint in our site wherein PayMongo will make a post request to. In Next.JS, it's as easy as creating a file under the pages/api folder. For now, let's fill up the pages/api/paymongo_webhook.js with an endpoint that prints out the request PayMongo sends us for testing.

pages/api/paymongo_webhook.js

// Webhook for paymongo payments

const handler = async (req, res) => {
  if (req.method === "POST") {
    console.log("===Webhook triggered===")
    const data = req.body.data
    console.log(data)
    console.log("===webhook end===")
    res.status(200).send("Webhook Received")
  }
  else {
    res.setHeader("Allow", "POST");
    res.status(405).send("Method Not Allowed");
  }
};

export default handler;

Let's test this out by creating a webhook and listening to a credit card payment.

Creating the webhook

We can easily create a webhook with PayMongo's Create a webhook API Reference. Enter your secret key in the username, enter your ngrok url + /api/paymongo_webhook in the url field (eg. https://4566-49-145-8-183.ngrok.io/api/paymongo_webhook), enter source.chargeable, payment.paid and payment.failed in the events field and click on "Try It". You can also use curl in doing this but doing it on the site is, personally, more hassle free.

This would create a webhook that you can use. Remember to list down your webhook ID, you can do it in a text file inside your project or add it in the .env file .

You can also do the following in the API Reference:

Do take note that every time you start your ngrok tunnel, it will give you a different url. You would have to update your webhook when the url changes.

Testing the webhook

You can now test out your webhook that we have just finished setting up. In localhost:8000, make a successful card payment. It might take a couple of seconds to reach your ngrok tunnel but it should log a post request and a console log. The console log contains what the payload looks like.

If you are not receiving any events after a couple of seconds, make sure that your webhook configurations are correct such as the url end point and the events array.

There are 3 different webhook events that we are listening to:

source.chargeable - when an e-wallet payment has been authorized by the client
payment.paid - when a card/PayMaya/GCash/GrabPay payment is successful
payment.failed - when a card/PayMaya payment fails

Accepting E-wallet Payments (GCash and GrabPay)

Now that we finished setting up our initial webhook end point, let's start accepting GCash and GrabPay. As mentioned in the first part of the tutorial, PayMongo uses the Source and Payment workflow to process GCash and GrabPay payments. Let's follow these steps as stated in the guide:

      - Create a Source
      - Have the customer authorize the payment
      - Create a Payment using the chargeable Source

Let's edit the src/components/payments/GCash.js and src/components/payments/GrabPay.js

Create a source

In both the e-wallet component files, I've already created a function called createSource. Let's fill up both of these functions and call the Create a Source API.

// In src/components/payments/GCash.js
// Function to Create A Source
  const createSource = async () => {
    setPaymentStatus("Creating Source")
    const options = {
      method: 'POST',
      headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json',
        Authorization: `Basic ${Buffer.from(publicKey).toString("base64")}`
      },
      body: JSON.stringify({
        data: {
          attributes: {
            amount: amount * 100,
            redirect: { success: 'http://localhost:3000/payment', failed: 'http://localhost:3000/payment' },
            billing: { name: `${name}`, phone: `${phone}`, email: `${email}` },
            type: 'gcash', //change to graby_pay in GrabPay.js
            currency: 'PHP'
          }
        }
      })
    }
    return fetch('https://api.paymongo.com/v1/sources', options)
      .then(response => response.json())
      .then(response => {
        return response
      })
      .catch(err => console.error(err));
  }

We can also create a front-end function to listen to the status of our payment source. We can use the Retrieve a Source API call for this.
In src/components/payments/GCash.js and src/components/payments/GrabPay.js

// Function to Listen to the Source in the Front End
  const listenToPayment = async (sourceId) => {
    let i = 5;
    for (let i = 5; i > 0; i--) {
      setPaymentStatus(`Listening to Payment in ${i}`)
      await new Promise(resolve => setTimeout(resolve, 1000))

      if (i == 1) {
        const sourceData = await fetch(
          'https://api.paymongo.com/v1/sources/' + sourceId,
          {
            headers: {
              // Base64 encoded public PayMongo API key.
              Authorization: `Basic ${Buffer.from(publicKey).toString("base64")}`
            }
          }
        ).then((response) => {
          return response.json()
        }).then((response) => {
          console.log(response.data)
          return response.data
        })

        if (sourceData.attributes.status === "failed") {
          setPaymentStatus("Payment Failed")
        }
        else if (sourceData.attributes.status === "paid") {
          setPaymentStatus("Payment Success")
        }
        else {
          i = 5;
          setPayProcess(sourceData.attributes.status)
        }
      }
    }
  }

Let's test this out by calling the two functions we made in our onSubmit function.

In src/components/payments/GCash.js and src/components/payments/GrabPay.js

const onSubmit = async (event) => {
     event.preventDefault();
    const source = await createSource();
    window.open(
      source.data.attributes.redirect.checkout_url, "_blank");
    listenToPayment(source.data.id)
  };

Have the customer authorize the payment

After creating the source and opening the checkout_url, we can simulate how a customer will authorize the payment.

Here we can observe that:

If the customer fails the payment, the source status stays at pending.
If the customer cancels the payment, the source status becomes cancelled
If the customer authorizes the payment, the source becomes chargeable.

Keep in mind that even if a source becomes chargeable, this does not mean that the payment is already successful. You still need to create a payment for the chargeable source. If you fail to do this after an hour, PayMongo would return the funds back to the customer's e-wallet and the status would become cancelled (see more). As you may have noticed, we'll also be able to see changes to our source on our webhook having the events source.chargeable and payment.failed.

Create a Payment using the chargeable Source

Theoretically, you could create a payment after listening in the front-end; however, it is not advisable. End users might close the window or lose internet connection so it is better to create the payment on webhooks.

Let's edit our src/pages/api/paymongo_webhook.js to handle this for us and call the Create a Payment API. Let us separate each event with an if-else statement.

In src/pages/api/paymongo_webhook.js

const handler = async (req, res) => {
  if (req.method === "POST") {
    console.log("===Webhook triggered===")
    const data = req.body.data
    console.log(data)
    console.log("===webhook end===")
    if (data.attributes.type === "source.chargeable") {
      // Gcash and Grab Pay
      console.log("E-wallet Payment Chargeable")

    }
    if (data.attributes.type === "payment.paid") {
      // All Payment Types
      // Add next steps for you
      console.log("Payment Paid")
    }
    if (data.attributes.type === "payment.failed") {
      // Failed Payments - Cards Paymaya
      // Add next steps for you
      console.log("Payment Failed")
    }
    res.status(200).send("Webhook Received")
  }
  else {
    res.setHeader("Allow", "POST");
    res.status(405).send("Method Not Allowed");
  }
};

export default handler;

Here, you can also do the your next steps after listening to the event. A great example of this is updating your checkout link or your transactions table in a database.

After separating our webhook events, let's create a payment every time a source becomes chargeable.

In src/pages/api/paymongo_webhook.js

...
    if (data.attributes.type === "source.chargeable") {
      // Gcash and Grab Pay
      console.log("E-wallet Payment Chargeable")

      // Create a payment resource
      const options = {
        method: 'POST',
        headers: {
          Accept: 'application/json',
          'Content-Type': 'application/json',
          Authorization: `Basic ${Buffer.from(
            process.env.PAYMONGO_SECRET
          ).toString("base64")}`,
        },
        body: JSON.stringify({
          data: {
            attributes: {
              amount: data.attributes.data.attributes.amount,
              source: { id: `${data.attributes.data.id}`, type: `${data.attributes.data.type}` },
              description: data.attributes.data.attributes.description,
              currency: 'PHP',
              statement_descriptor: data.attributes.data.attributes.statement_descriptor
            }
          }
        })
      };

      fetch('https://api.paymongo.com/v1/payments', options)
        .then(response => response.json())
        .then(response => console.log(response))
        .catch(err => console.error(err));

    }
...

After doing so, we should now be able to accept e-wallet payments successfully. The webhook would log a source.chargeable event and then log a payment.paid event.

Conclusion

In this guide, you learned how to use PayMongo webhooks and accepting GrabPay and GCash Payments. This concludes the two part series and I hope you like this article and feel free to give feedbacks on my writing.

Integrating PayMongo API in Next.js - Part 1

xunylpay — Mon, 27 Dec 2021 07:05:45 +0000

Hi there,

In this two part article, I'll be guiding you on how to integrate the PayMongo API in NextJS

In Part 1, we have a brief discussion on PayMongo payment workflows and how to setup credit card payments.

In Part 2, we tackle using webhooks to monitor payments and we move forward to processing GrabPay and GCash Payments.

Introduction
- Demo
- PayMongo Payment Workflows
Let's Build
- Setting Up
- Running the project
- Implementing Card Payments
- Creating a PaymentIntent from the server-side
- Collect Card Information from the client-side
- Send Card Information to PayMongo
- Monitoring PaymentIntents through webhooks
Conclusion

Introduction

PayMongo provides businesses an easy, user-friendly way to accept payments from their customers. It is a payment gateway that process Visa/Mastercard, GCash, and GrabPay payments.

Demo

Live Preview: https://nextjs-paymongo-api.vercel.app/
GitHub: https://github.com/xunylpay/nextjs-paymongo-api

PayMongo Payment Workflows

Before diving into the code, I would like to discuss PayMongo's two Payment Workflows. These workflows differ in implementation and payment method. I have summarized the steps below:

1.Payment Intent Payment Method Workflow

This is what PayMongo uses to process credit card and PayMaya payments. It involves creating a payment intent, creating a payment method, and then attaching the intent and method together.

      - Creating a PaymentIntent from the server-side
      - Collect Card Information from the client-side
      - Send Payment Information to PayMongo
      - Monitoring PaymentIntents through webhooks

2.Source and Payment Workflow

This is what PayMongo uses to process GCash and GrabPay payments. This involves creating a source, listening to customer authorization, and creating a payment for chargeable source.

      - Create a Source
      - Have the customer authorize the payment
      - Create a Payment using the chargeable Source

Let's Build

Setting Up

As mentioned in the title, we'll be using Next.js for building this.

For Next.js to work, we need to have Node.js and npm installed.

So, first, install Node.js if you haven't yet.

Let's also download yarn



npm install --global yarn

Additionally, you also need a PayMongo Account. You can sign up here and get your test API keys at the developers tab.

Lastly, to follow along this tutorial, we will be starting with the front end already built. Feel free to download or clone the front-end-done branch in the repository.

I built this simple front-end to simulate a simple payment process. The site uses localstorage to simulate database push and pull requests. We will be primarily concerned with the src/components/payments folder and src/pages/api/createPaymentIntent.js file.

Running the project

Now open the project in your favorite text editor or IDE (Integrated Development Environment). Open a terminal then run the following commands to start up the development server.



yarn
yarn dev

On localhost:3000 you should be seeing this:

Next, create a .env file on the root folder. Insert your public and secret keys in this format:



NEXT_PUBLIC_PAYMONGO_PUBLIC=pk_test_xxxxxxxxxxxxxxxxxxxxxxxx
PAYMONGO_SECRET=sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

The NEXT_PUBLIC_ is important when exposing the environment variable in the front end

Implementing Card Payments

As mentioned previously, the payment intent payment method workflow is used when implementing card payments. Let's do the steps provided in the PayMongo Accepting Cards Documentation

Creating a PaymentIntent from the server-side

In the src/pages/api/createPaymentIntent.js file, let us create an endpoint that would allow us to create a PaymentIntent given a POST request. The req.body should contain the necessary information as required by the Create A PaymentIntent API call.

As per the API reference, we need to authenticate our API requests. PayMongo uses HTTP Basic Auth and your API key as the basic auth username, encoded in Base64. This may seem complicated but it is really easy to implement in JavaScript as shown below.

src/pages/api/createPaymentIntent.js



// This function is called to create a Payment intent
// Step 1 of https://developers.paymongo.com/docs/accepting-cards

export default async function handler(req, res) {
  if (req.method === "POST") {

    // Creating our options for the Create a Payment Intent Call
    const optionsIntent = {
      method: "POST",
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
        Authorization: `Basic ${Buffer.from(
          process.env.PAYMONGO_SECRET
        ).toString("base64")}`, // HTTP Basic Auth and Encoding
      },
      body: JSON.stringify(req.body),
      // The req.body should follow this specific format
      //   {
      //     "data": {
      //          "attributes": {
      //               "amount": 10000 (int32) note that 10000 = PHP 100.00,
      //               "payment_method_allowed": [
      //                    "card",
      //                    "paymaya"
      //               ](string array),
      //               "payment_method_options": {
      //                    "card": {
      //                         "request_three_d_secure": "any"
      //                    }
      //               },
      //               "currency": "PHP" (string),
      //               "description": "description" (string),
      //               "statement_descriptor": "descriptor business name" (string)
      //          }
      //     }
      //  }
    };

    // Calling the Create a Payment Intent API
    await fetch("https://api.paymongo.com/v1/payment_intents", optionsIntent)
      .then((response) => response.json())
      .then(async (response) => {
        if (response.errors) {
          console.log(JSON.stringify(response.errors));
        } else {
          res.status(200).json({ body: response });
        }
      });
  } else {
  }
}

In the src/components/payments/CreditCard.js, we fill up the createPaymentIntent so that the function calls the src/pages/api/createPaymentIntent.js we just made. Keep in mind that we are using data from component props, but you can handle it in any way that you like.

src/components/payments/CreditCard.js - createPaymentIntent



// Function to Create a Payment Intent by calling the site's api
  const createPaymentIntent = async () => {
    setPaymentStatus("Creating Payment Intent");
    const paymentIntent = await fetch("/api/createPaymentIntent", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        data: {
          attributes: {
            amount: amount * 100,
            payment_method_allowed: ["card"],
            payment_method_options: {
              card: { request_three_d_secure: "any" },
            },
            currency: "PHP",
            description: description,
            statement_descriptor: "descriptor business name",
          },
        },
      }),
    })
      .then((response) => {
        return response.json();
      })
      .then((response) => {
        return response.body.data;
      });

    return paymentIntent;
  };

Collect Card Information from the client-side

The starter template already included this. I handled this by simply creating a useState for all the fields and setting the value on change. PayMongo does not recommend to send this data on the server or store it anywhere. We will be using this card information on the next step.

Send Card Information to PayMongo

To send card information to PayMongo securely we will be creating a paymentMethod and attaching it to the paymentIntent we created in the first step.

In calling the creating a payment method, we use the card details that the client provided. We also use our public key encoded in the base64 when calling the API Call.

src/components/payments/CreditCard.js - createPaymentMethod



// Function to Create a Payment Method by calling the PayMongo API
  const createPaymentMethod = async () => {
    setPaymentStatus("Creating Payment Method");
    const paymentMethod = fetch("https://api.paymongo.com/v1/payment_methods", {
      method: "POST",
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
        Authorization: `Basic ${Buffer.from(process.env.NEXT_PUBLIC_PAYMONGO_PUBLIC).toString("base64")}`,
      },
      body: JSON.stringify({
        data: {
          attributes: {
            details: {
              card_number: `${number}`, //"4343434343434345",
              exp_month: parseInt(`${month}`), //2
              exp_year: parseInt(`${year}`), //22
              cvc: `${code}`, //"123",
            },
            billing: {
              name: `${name}`,
              email: `${email}`,
              phone: `${phone}`,
            },
            type: "card",
          },
        },
      }),
    })
      .then((response) => {
        return response.json();
      })
      .then((response) => {
        return response.data;
      })
      .catch((err) => {
        console.log(err);
        setPaymentStatus(err);
        return err;
      });

    return paymentMethod;
  };

Now, to complete the credit card payment, we attach the payment intent and the payment method we created together.

Here, we need to keep in mind two scenarios. Basic cards and 3DS cards. 3DS cards are cards where we need to handle a page wherein the user will enter their OTP (One Time Pin). The OTP is part of the 3DS protocol implemented by banks for clients to approve their online transactions. Basic cards are rare in the Philippines, and almost all PayMongo card transactions are done with 3DS cards. We render this page by creating an iframe or opening a window as seen below.

src/components/payments/CreditCard.js - attachIntentMethod



// Function to Attach a Payment Method to the Intent by calling the PayMongo API
  const attachIntentMethod = async (intent, method) => {
    setPaymentStatus("Attaching Intent to Method");
    fetch(`https://api.paymongo.com/v1/payment_intents/${intent.id}/attach`, {
      method: "POST",
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
        Authorization: `Basic ${Buffer.from(process.env.NEXT_PUBLIC_PAYMONGO_PUBLIC).toString("base64")}`,
      },
      body: JSON.stringify({
        data: {
          attributes: {
            payment_method: `${method.id}`,
            client_key: `${intent.attributes.client_key}`,
          },
        },
      }),
    })
      .then((response) => response.json())
      .then((response) => {
        const paymentIntent = response.data;
        console.log(paymentIntent)
        const paymentIntentStatus = paymentIntent.attributes.status;
        if (paymentIntentStatus === 'awaiting_next_action') {
          // Render your modal for 3D Secure Authentication since next_action has a value. You can access the next action via paymentIntent.attributes.next_action.
          setPaymentStatus(paymentIntentStatus);
          window.open(
            paymentIntent.attributes.next_action.redirect.url, "_blank");
        } else {
          setPaymentStatus(paymentIntentStatus);
        }
      })
      .catch((err) => {
        console.log(err);
        setPaymentStatus(JSON.stringify(err));
      });
  };

Now, let's call up these functions in our submit function.

src/components/payments/CreditCard.js - onSubmit



const onSubmit = async (event) => {
    event.preventDefault();
    const paymentIntent = await createPaymentIntent();
    const paymentMethod = await createPaymentMethod();
    await attachIntentMethod(paymentIntent, paymentMethod);
};

Monitoring PaymentIntents through webhooks

The last step of the Payment Intent Payment Method workflow is monitoring the payment intent through the use of webhooks. We'll discuss this in the next part of the guide. However, we can still monitor paymentIntents in the client side by calling the Retrieve a Payment Intent API. Let us create this function and call it after attaching the payment intent and method.

This is kind of a hack to set a timeout that for every 5 seconds we check the status by calling the API until payment is resolved.

src/components/payments/CreditCard.js - listenToPayment



// Function to Listen to the Payment in the Front End
  const listenToPayment = async (fullClient) => {
    const paymentIntentId = fullClient.split('_client')[0];
    let i = 5;
    for (let i = 5; i > 0; i--) {
      setPaymentStatus(`Listening to Payment in ${i}`)
      await new Promise(resolve => setTimeout(resolve, 1000))

      if (i == 1) {
        const paymentIntentData = await fetch(
          'https://api.paymongo.com/v1/payment_intents/' + paymentIntentId + '?client_key=' + fullClient,
          {
            headers: {
              // Base64 encoded public PayMongo API key.
              Authorization: `Basic ${Buffer.from(process.env.NEXT_PUBLIC_PAYMONGO_PUBLIC).toString("base64")}`
            }
          }
        ).then((response) => {
          return response.json()
        }).then((response) => {
          console.log(response.data)
          return response.data
        })

        if (paymentIntentData.attributes.last_payment_error) {
          setPaymentStatus(JSON.stringify(paymentIntentData.attributes.last_payment_error))
        }
        else if (paymentIntentData.attributes.status === "succeeded") {
          setPaymentStatus("Payment Success")
        }
        else {
          i = 5;
        }
      }
    }
  }

In attachIntentMethod, we listen to the status of the payment intent after opening the OTP page.

src/components/payments/CreditCard.js - attachIntentMethod



...
      .then((response) => response.json())
      .then((response) => {
        const paymentIntent = response.data;
        console.log(paymentIntent)
        const paymentIntentStatus = paymentIntent.attributes.status;
        if (paymentIntentStatus === 'awaiting_next_action') {
          // Render your modal for 3D Secure Authentication since next_action has a value. You can access the next action via paymentIntent.attributes.next_action.
          setPaymentStatus(paymentIntentStatus);
          window.open(
            paymentIntent.attributes.next_action.redirect.url, "_blank");
            listenToPayment(paymentIntent.attributes.client_key);
        } else {
          setPaymentStatus(paymentIntentStatus);
        }
      })
      .catch((err) => {
        console.log(err);
        setPaymentStatus(JSON.stringify(err));
      });
...

After doing this, the app should be able to accept Credit card payments that would reflect on your PayMongo dashboard. PayMongo conveniently provides test cards that you can use for testing here.

Conclusion

In this guide, you learned how to use PayMongo API keys, PayMongo payment workflows, and accepting credit card payments. For the next part of the guide, we'll learn more about webhooks and using the payment source and payment to process e-wallet transactions (GCash and GrabPay).

DEV Community: xunylpay

Integrating PayMongo API in Next.js - Part 2

Hi there,

Table of Contents

Introduction

Demo

Webhooks

Let's Code

Setting Up

Running the project

Creating an endpoint for the webhook

Creating the webhook

Testing the webhook

Accepting E-wallet Payments (GCash and GrabPay)

Create a source

Have the customer authorize the payment

Create a Payment using the chargeable Source

Conclusion

Integrating PayMongo API in Next.js - Part 1

Hi there,

Table of Contents

Introduction

Demo

PayMongo Payment Workflows

Let's Build

Setting Up

Running the project

Implementing Card Payments

Creating a PaymentIntent from the server-side

Collect Card Information from the client-side

Send Card Information to PayMongo

Monitoring PaymentIntents through webhooks

Conclusion