React hooks for Yoco Gateway

v2.2.1 🎉 - Now with EFT.

React hooks and components for accepting card and EFT payments in your React application with Yoco Gateway.

Installation

yarn add @lekkercommerce/yoco-react

Getting Started

The Yoco Popup offers you the quickest and easiest way to accept online card payments.

You can use the usePopup hook to present the payment form in your React application.

The hook returns a showPopup method used to trigger the pop-up. It also returns variable isYocoReady for use in determining whether the Yoco SDK is loaded and ready or not.

The hook itself accepts two parameters:

• Your Yoco public key. Learn how to get one on the Yoco website.
• The payment ID for the checkout that will have been initiated with a server-to-server call on the backend. Learn more about payment initiation.

🛠️ Use the Postman collection to quickly create test payments.

The showPopup method expects a callback. This callback will receive the YocoCheckoutResult when the pop-up completes processing a payment. Additionally, it requires an onClose method to be invoked when a user dimisses the pop-up. Finally, it will expect a currency and an amountInCents.

Here's an example implementation:

import React, { FC }  from 'react';
import { usePopup } from '@lekkercommerce/yoco-react';

const PopupExample: FC = () => {
  const [showPopup, isYocoReady] = usePopup('your_public_key', 'a_valid_payment_id');

  async function callback(result: YocoCheckoutResult) {
    if (result.error) {
      // handle failure
      // result.error.message - Error message
      // result.error.status  - Error status
      return;
    }
    // result.id has the payment's id for verification
  }

  async function onClose() {
    // handle pop-up dismissal
  }

  async function onSubmit() {
    showPopup({ amountInCents: 1000, callback, currency: 'ZAR', onClose });
  }

  return (
    <button disabled={!isYocoReady} onClick={onSubmit}>Pay</button>
  );
}

You can view the full list of configuration options for the showPopup method in the usePopupHook reference.

Verifying successful payments

The result will have a value of "succeeded" in the status property for a successful payment. It also has an id that you can use for verifying a payment with a server-to-server call. Learn how to use the API in the official guide.

The Postman collection has a payment verification helper.

useYoco hook

If all you need is the base Yoco SDK without the hooks and components, the library exposes a useYoco hook.

import { useYoco } from '@lekkercommerce/yoco-react';

...

const yocoSDK = useYoco(publicKey);

You can then use the SDK as normal according to the official docs. It is the same hook used internally by the rest of the hooks in this library.

The hook expects your Yoco public key, and optionally a payment ID depending on your use case.

You may also use the useYocoLegacy hook to get the previous generation SDK (https://js.yoco.com/sdk/v1/yoco-sdk-web.js). This may be useful if you prefer to use the inline checkout experience which is currently not available in v2.0.0.

Accepting EFT payments

You can easily accept instant EFT payments in your React application with the useEFT hook. The hook takes a public key as the only parameter and returns a showEFT method and a boolean variable isYocoReady.

To display an EFT pop-up, call the showEFT method with the id of the payment you would have prepared in a server-to-server call.

import React from 'react';
import { useEFT } from '@lekkercommerce/yoco-react';

const App = () => {
  const [showEFT, isYocoReady] = useEFT('your_public_key');
  async function onSubmit() {
    try {
      const result = await showEFT({ id: 'your_payment_id' });
      if (result.error) {
        // handle failure
        // result.error.message - Error message
        // result.error.status  - Error status
        return;
      }
      if (result.status === "succeeded") {
        // handle success for result.id
        return;
      }
      // handle payment statuses that are not successes.
      // for example, the user can dismiss the EFT pop-up
      // resulting in a status of "cancelled"
    } catch (err) {
      // handle general failures
    }
  }

  return (
    <button disabled={!isYocoReady} onClick={onSubmit}>Pay</button>
  );
};

Inline Checkouts

Inline checkouts will be available in a future release.

Playground

The playground is a quick way to try out the different hooks:

cd example && yarn start

See CONTRIBUTING.md for more.

Support

If you have any questions, feedback or you are experiencing issues integrating, please contact [email protected].