npm package: @mybusinessapp/react-checkout
Description: React components for Checkout.js
Author: MyBusiness App
Latest version: 2.0.7

<img src="https://i.imgur.com/gGxJ8zx.png" align="right" />

# react-checkout &middot; [![build status][travis-image]][travis-url] [![coverage][coverage-image]][coverage-url] [![contributor covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)


React components for [Checkout.js][docs-checkout-js]

## Documentation

[Documentation & Reference][docs]

[Checkout.js Documentation][docs-checkout-js]

## Examples

[Interactive Demo][demo]

A great way to get started is to try the [interactive demo][demo] in our documentation, and look through the [demo source][demo-src] on GitHub.

## Installation

Install this package with npm

```bash
npm install @mybusiness-app/react-checkoutcheckout
```

Then, include checkout.js in your application via our CDN.

```html
<script src="https://js.mybusinessapp.co.za/v4/checkout.js"></script>
<!-- optional: include checkout.css -->
<link rel="stylesheet" href="https://js.mybusinessapp.co.za/v4/checkout.css">
```

## Implementation Guide

In this guide, we will cover the steps necessary to **create a payment form** that will submit your user's payment information to Checkout.

> ℹ️ If you haven't yet, please review the [Checkout.js documentation][docs-checkout-js]. This will give you a solid understanding of the total capabilities of the library before we begin implementing some of its features in React.

To start, we will use the [&lt;CheckoutProviderr />][docs-component-checkout-provider] component to set our [public key][app-api-access].

```jsx
// app.js
import React from 'react';
import { CheckoutProvider } from '@mybusinessapp/react-checkout';

function App () {
  return (
    <CheckoutProvider publicKey="MY_PUBLIC_KEY" />
  );
}
```

Now we can set up our payment form. For this, we will use [Checkout.js Elements][docs-checkout-js-elements]. First, we will use the [&lt;Elements />][docs-component-elements] component to group our Elements together. We'll also create a `<MyPaymentForm />` component to contain our payment form.

```jsx
// app.js
import React from 'react';
import { CheckoutProvider, Elements } from '@mybusinessapp/react-checkout';
import { MyPaymentForm } from './my-payment-form';

function App () {
  return (
    <CheckoutProvider publicKey="MY_PUBLIC_KEY">
      <Elements>
        <MyPaymentForm />
      </Elements>
    </CheckoutProvider>
  );
}
```

Within our new `<MyPaymentForm />` component, we'll add a [&lt;CardElement />][docs-component-card-element] which will render a secure card element. We'll also add inputs for our users' name. To let react-checkout know that we want to use these fields, we'll use a `data-checkout` attribute. To include additional properties, see [this billing fields table][docs-checkout-js-billing-fields].

```jsx
// my-payment-form.js
import React from 'react';
import { CardElement } from '@mybusinessapp/react-checkout';

export function MyPaymentForm (props) {
  return (
    <form>
      <input type="text" data-checkout="first_name" placeholder="First name" />
      <input type="text" data-checkout="last_name" placeholder="Last name" />
      <CardElement />
    </form>
  );
}
```

We are now ready to add the final step: **getting a token**. When our users submit our form, we want to send their payment information to Checkout, which will return a token. We'll then keep this token to use in the MyBusiness App API.

To accomplish this, we will use the [useCheckout][docs-hook-use-checkout] hook. This hook returns a Checkout.js instance, on which we will call [checkout.token][docs-checkout-js-token]. Since this function expects a `<form>`, we will create a [React ref](react-refs) to pass to it.

```jsx
// my-payment-form.js
import React from 'react';
import { CardElement, useCheckout } from '@mybusinessapp/react-checkout';

export function MyPaymentForm (props) {
  const formRef = React.useRef();
  const checkout = useCheckout();

  function handleSubmit (event) {
    event.preventDefault();
    checkout.token(formRef.current, (err, token) => {
      if (err) {
        // handle error
      } else {
        // save the token.id, and submit it to the Checkout API from your server
      }
    });
  }

  return (
    <form onSubmit={handleSubmit} ref={formRef}>
      <input type="text" data-checkout="first_name" placeholder="First name" />
      <input type="text" data-checkout="last_name" placeholder="Last name" />
      <CardElement />
    </form>
  );
}
```

With that, we have implemented the essential components of a payment form using react-checkout. The tokens generated above may be used on any `billing_info` object in the [MyBusiness App API][docs-mybusinessapp-api].

### Additional Usage

React-checkout also includes a [useCheckoutPricing][docs-hook-use-checkout-pricing] hook for generating a pricing preview before checking out.

```js
import { useCheckoutPricing, CheckoutProvider } from '@mybusinessapp/react-checkout';

function PricingPreview () {
  const initialPricingInput = {
    subscriptions: [
      {
        plan: 'my-plan'
      }
    ]
  };

  const [{ price, loading }, setCheckoutPricing] = useCheckoutPricing(initialPricingInput);

  if (!loading) {
    return <div>{price.now.subtotal}</div>
  };
};

export default function MyApp () {
  <CheckoutProvider>
    <PricingPreview />
  </CheckoutProvider>
};
```

For more details, see the [useCheckoutPricing Documentation][docs-hook-use-checkout-pricing].

## Additional resources

* [Documentation & Reference][docs]
* [Checkout.js Documentation][docs-checkout-js]
* [Interactive Demo][demo]
* [Code on GitHub][github]
* [Package on npm][npm]
* [Checkout API Documentation][docs-checkout-api]
* Questions? [GitHub issues][github-issues] and [MyBusiness App support][support] are here for you.

## Licence

MIT

[github]: https://github.com/mybusiness-app/react-checkout
[github-issues]: https://github.com/mybusiness-app/react-checkout/issues
[npm]: https://www.npmjs.com/package/@mybusiness-app/react-checkout
[travis-url]: https://travis-ci.org/recurly/react-checkout/builds
[travis-image]: https://img.shields.io/travis/recurly/react-checkout/main.svg?style=flat-square
[coverage-url]: https://coveralls.io/github/recurly/react-checkout
[coverage-image]: https://img.shields.io/coveralls/github/recurly/react-checkout.svg?style=flat-square

[docs]: https://recurly.github.io/react-checkout
[docs-component-checkout-provider]: https://recurly.github.io/react-checkout/?path=/docs/components-recurlyprovider--docs
[docs-component-elements]: https://recurly.github.io/react-checkout/?path=/docs/components-elements--docs
[docs-component-card-element]: https://recurly.github.io/react-checkout/?path=/docs/components-card-element--default
[docs-hook-use-checkout]: https://recurly.github.io/react-checkout/?path=/docs/hooks-userecurly--docs
[docs-hook-use-checkout-pricing]: https://recurly.github.io/react-checkout/?path=/docs/hooks-usecheckoutpricing--docs

[docs-checkout-js]: https://developers.recurly.com/reference/recurly-js/
[docs-checkout-js-elements]: https://developers.recurly.com/reference/recurly-js/#elements
[docs-checkout-js-billing-fields]: https://developers.recurly.com/reference/recurly-js/#billing-fields
[docs-checkout-js-token]: https://developers.recurly.com/reference/recurly-js/#getting-a-token
[docs-checkout-api]: https://developers.recurly.com/api

[demo]: https://recurly.github.io/react-checkout/?path=/docs/introduction-interactive-demo--docs
[demo-src]: https://github.com/mybusiness-app/react-checkout/tree/main/demo
[card-element-demo.js]: https://github.com/mybusiness-app/react-checkout/demo/src/card-element-demo.js

[app-api-access]: https://app.recurly.com/go/developer/api_access
[support]: https://recurly.zendesk.com

[react-refs]: https://reactjs.org/docs/refs-and-the-dom.html