React Square Hosted Fields

A react component for Square's hosted fields

What this Is

A quick way of plugging in your App ID to Square's hosted payment fields in a react environment.

Getting Started

You can get started with the React payment form in a few easy steps:

npm install --save react-square-hosted-fields

Simple Usage

Import the payment form:

import SquarePaymentForm from 'react-square-hosted-fields';

Put the payment form anywhere:

<SquarePaymentForm appId="YOUR-SQUARE-APPLICATION-ID" onNonceGenerated={this.handleNonce} />

Using a GET Resource

You can either plug in your application id directly via the appId prop as it's done above, or use the get prop to specify a get resource.

<SquarePaymentForm get="/some/api/path" onNonceGenerated={this.handleNonce} onGetAppIdError={this.handleGetError} />

Don't forget to handle an error with your resource! The component expects the resource to return a json object like this:

{ appId: 'YOUR-SQUARE-APPLICATION-ID' }

Square Options

A majority of the options match what goes into Square's SqPaymentForm. See the docs for more clarification there.

Prop | Type | Default | Description --------------------------- | ------- | ------------------------- | --------------------------------------------------------------------------------- appId | String | '' (Required ifn get) | Your Square Application ID get | String | '' (Required ifn appId) | URL or path to a GET resouce, handled with promises submitText | String | Submit Payment | The text that shows up on the submit button to generate a nonce inputClass | String | sq-input | The class name(s) that will be put into iframe elements for styling the inputs inputStyles | Array | [] | Array of input style objects as per SqPaymentForm docs cardNumber.elementId | String | sq-card-number | The element id that SqPaymentForm will replace with the card number field cardNumber.placeholder | String | E.g. XXXX-XXXX-XXXX-XXXX| The placeholder text for the card number field once replaced by SqPaymentForm cvv.elementId | String | sq-cvv | The element id that SqPaymentForm will replace with the CVV field cvv.placeholder | String | E.g. XXX | The placeholder text for the CVV field once replaced by SqPaymentForm expirationDate.elementId | String | sq-expiration-date | The element id that SqPaymentForm will replace with the expiration date field expirationDate.placeholder | String | MM/YY | The placeholder text for the expiration date field once replaced by SqPaymentForm postalCode.elementId | String | sq-postal-code | The element id that SqPaymentForm will replace with the postal code field postalCode.placeholder | String | E.g. XXXXX | The placeholder text for the postal code field once replaced by SqPaymentFor

Callbacks

The component comes with a few callbacks that you can use to loading or user events with the form. See Square's SqPaymentForm for more details on SqPaymentForm

Prop | Parameters | Fires ----------------------------- | ----------------------------- | ------------------------------------------------------------------------ onGetAppIdError | Object axiosError | If the get prop is specified and the API resource returns an error code onScriptCreated | | As soon as the SqPaymentForm client library script tags are created and put into the DOM onScriptError | | When the SqPaymentForm client library encounters an error while loading onScriptLoaded | | When the SqPaymentForm client library is finished loading and ready for use onPaymentFormLoaded | | After a new instance of SqPaymentForm is created onInputEventReceived | String inputEvent | Whenever a user does something to the payment form, Square fires their own [inputEvent]((https://docs.connect.squareup.com/articles/adding-payment-form) object onUnsupportedBrowserDetected | | If SqPaymentForm has determined the user's browser is not supported onNonceRequested | | As soon as the user clicks the submit button for the form (throws an error if it happens before the payment form is generated) onNonceGenerated | String nonce, Object cardData | When a payment nonce has been generated successfully onNonceError | Array errors | When Square reports an error while generating a payment nonce

Styling Options

There are also a few options specific to this package that can help style the form. Note that no styling is done on the form other than what Square does by default.

Prop | Type | Default | Description --------------------------- | ------- | ------------------------- | ------------------------------------------------------------------------------------------------------- componentWrapperClass | String | sq-component-wrapper | Class name(s) for the div that wraps the entire component formWrapperClass | String | sq-form-wrapper | Class name(s) for the div that wraps the entire form fieldsWrapperClass | String | sq-fields-wrapper | Class name(s) for the div that wraps only the input fields (not the submit button) buttonWrapperClass | String | sq-button-wrapper | Class name(s) for the div that wraps only the submit button inputWrapperClass | String | sq-input-wrapper | Class name(s) for the div that wraps each input field (iframe) cardWrapperClass | String | sq-card-wrapper | Class name(s) for the div that wraps the card input field (would override inputWrapperClass) cvvWrapperClass | String | sq-cvv-wrapper | Class name(s) for the div that wraps the cvv input field (would override inputWrapperClass) expirationWrapperClass | String | sq-expiration-wrapper | Class name(s) for the div that wraps the expiration date input field (would override inputWrapperClass) postalWrapperClass | String | sq-postal-wrapper | Class name(s) for the div that wraps the postal code input field (would override inputWrapperClass)

The submit button can be styled using .buttonWrapperClass button, as it's simply a button element.

Using Custom Elements

The component also supports the ability to use children within the component itself if you already have a payment form styled.

<SquarePaymentForm get="/some/api/resource" onNonceGenerated={this.handleNonce}>
  <div className="some-custom-wrapper">
    <CustomWrapper>
      <CustomComponent>Card Number</CustomComponent>
      <div className="my-own-class" id="sq-card-number"></div>
    </CustomWrapper>

    <CustomWrapper>
      <CustomComponent>Card Number</CustomComponent>
      <div className="my-own-class" id="sq-cvv"></div>
    </CustomWrapper>
    
    <CustomWrapper>
      <CustomComponent>Card Number</CustomComponent>
      <div className="my-own-class" id="sq-expiration-date"></div>
    </CustomWrapper>
    
    <CustomWrapper>
      <CustomComponent>Card Number</CustomComponent>
      <div className="my-own-class" id="sq-postal-code"></div>
    </CustomWrapper>
  </div>
</SquarePaymentForm>

Do not forget to include the id props for your divs and make sure they match with the props elementId props you send into the component (the defaults are used in the example). If you don't, SqPaymentForm will not be able to find the divs to replace with iframes.

Note that the submit payment button will be included as part of the component. If you have a way around this, please suggest it.

More Information

If you see something you think is missing or would like to contribute, please check out the Bitbucket repo