search

2140data / react-btcpay-paybutton

Accept BTC payments in your React app with BTCPay Server Pay Button
MIT License
15 stars 7 forks source link

readme

React BTCPay Server Pay Button

Overview

The React BTCPay Server Pay Button offers a seamless and highly configurable solution for integrating BTCPay Server functionality into your React application. Enable Bitcoin payment processing in your app with just three simple steps.

Features

Table of Contents

Requirements

Before You Begin

This project assumes your BTCPay Server is already set up and your Pay Button is turned ON. You should also have your wallet set up and have channels with inbound liquidity (if accepting Lightning payments).

Refer to the BTCPay Server documentation for more information.

::warning:: The BTCPay Server Pay Button should only be used for tips and donations. Using the pay button for e-commerce integrations is not recommended since order relevant information can be modified by the user. For e-commerce, you should use BTCPay Server's Greenfield API. If your app processes commercial transactions, you should create a separate store before using the pay button.

Installation

RECOMMENDED: Package Installation

  1. Install the Package: Open your Terminal or other command line interface and run the following command to install the react-btcpay-paybutton package into your React project. 
    npm install react-btcpay-paybutton
  2. Proceed to Next Step: Once the package is installed, move on to Import the Component to integrate the ReactBtcPayButton into your app.

Optional: Manual Installation

  1. Download the File: Download and copy the ReactBtcPayButton.jsx file into your React app folder.
  2. Import the Component: Use the following import statement in your React file where you want to use the component (be sure to use the correct path/to/ReactBtcPayButton.jsx): 
    import { ReactBtcPayButton } from 'path/to/ReactBtcPayButton.jsx';
  3. Proceed to Next Step: After importing, you can move on to Add Component to Your App.

Quick Start

Here's how you can add the React BTCPay Server Pay Button to your application:

Step 1: Import the Component

import { ReactBtcPayButton } from 'react-btcpay-paybutton';

Step 2: Add Component to Your App

To integrate the React BTCPay Button into your application, simply include it in your JSX (with minimum required settings):

<ReactBtcPayButton
  btcPayDomain="YourServer.com" // Your BTCPay Server URL
  storeId="YourStoreID" // Your BTCPay Server Store ID
  // Additional options as needed (see Step 3 below)
/>

Step 3: Customize Settings and Design

The ReactBtcPayButton component accepts various props that allow you to customize its behavior and appearance. Below are detailed explanations for each of these props:

:red_circle: REQUIRED Props

Prop Type Description Default Value Available Options
btcPayDomain string :red_circle: REQUIRED The domain where your BTCPay Server is hosted. '' Add a URL
storeId string :red_circle: REQUIRED The ID of your store on the BTCPay Server. '' Add a URL

OPTIONAL Additional Props

Prop Type Description Default Value Available Options
browserRedirect string The URL for browser redirection after payment. '' Add a URL
checkoutDesc string Description that appears on the checkout invoice. '' Add a description
currency string Specifies the default currency for payments. MORE INFO 'SATS' 'SATS', 'BTC'
currencyOptions array of strings Defines the currencies inside the BTCPay form's Currency dropdown. MORE INFO ['SATS', 'BTC'] ['SATS', 'BTC', 'USD', 'EUR', 'CAD', 'AUD', 'JPY', 'GBP']
defaultPaymentMethod string Specifies the payment method that will be used to process transactions. MORE INFO '' '', 'BTC_LightningLike', 'BTC'
imageShow boolean Choose to show or hide the BTCPay logo on button. true true, false
imageSize string Specifies the height for the BTCPay logo on button. '46px' Enter any CSS size (px, % or rem)
inputMax number Specifies the maximum amount for the input field. 21000000000000 Enter a number
inputMin number Specifies the minimum amount for the input field. 1 Enter a number
mode string Select a display mode for the BTCPay Pay Button fields. MORE INFO 'Slider' 'Fixed', 'Slider', 'Custom'
notifyEmail string The email address for transaction notifications. '' Add an email address
orderId string An identifier for the order. '' Add an order number
serverIpn string The URL for Instant Payment Notifications (IPN). '' Add a URL
sliderMax number Specifies the maximum value for the payment slider. 250000 Enter a number
sliderMin number Specifies the minimum value for the payment slider. 1 Enter a number
submitBtnText string The text displayed on the submit button. 'Pay with' Add text

OPTIONAL Style Props

Prop Type Description Default Value Available Options
amountInputStyles object Override input field styles. LISTED BELOW Any CSS
(JS Object)
formStyles object Override form styles. LISTED BELOW Any CSS
(JS Object)
plusMinusButtonStyles object Override plus/minus button styles. LISTED BELOW Any CSS
(JS Object)
rangeInputStyles object Override slider styles. LISTED BELOW Any CSS
(JS Object)
submitButtonStyles object Override button styles. LISTED BELOW Any CSS
(JS Object)
submitButtonTextStyles object Override button text styles. LISTED BELOW Any CSS
(JS Object)

How to Use ReactBtcPayButton Props

REQUIRED Props

btcPayDomain (Required)

storeId (Required)

OPTIONAL Additional Props

browserRedirect

checkoutDesc

currency

currencyOptions

:warning: IMPORTANT :warning:
If you add new currencies, you must set a 'Preferred Price Source' in BTCPay Server under Store Settings > Rates. See the BTCPay documentation

defaultPaymentMethod

imageShow

imageSize

inputMax

inputMin

mode

notifyEmail

orderId

serverIpn

sliderMax

sliderMin

submitBtnText

OPTIONAL Style Props

amountInputStyles

formStyles

plusMinusButtonStyles

rangeInputStyles

submitButtonStyles

submitButtonTextStyles

Advanced Usage Example

Advanced Usage Example showing ALL available options:
Scroll down for all CSS styles (as JS objects)

<ReactBtcPayButton
  // === REQUIRED Props ===
  btcPayDomain='server.com' // REQUIRED - BTCPay Server domain
  storeId='storeid' // REQUIRED - BTCPay Server Store ID

  // === OPTIONAL Additional Props === 
  browserRedirect='https://redirect.com' // Browser redirect URL
  checkoutDesc='Thank you for your payment!' // Invoice description
  currency='SATS' // Default currency for invoices
  currencyOptions={['SATS', 'BTC', 'USD', 'EUR', 'CAD', 'AUD', 'JPY', 'GBP']} // Options for dropdown
  defaultPaymentMethod='' // How BTCPay Server will process transactions
  imageShow={true} // BTCPay logo in button? {true} or {false}
  imageSize='46px' // BTCPay Server logo height
  inputMax={21000000000000} // Input field maximum
  inputMin={1} // Input field minimum
  mode='Slider' // Form Options: 'Fixed', 'Custom', 'Slider'
  notifyEmail='email@youremail.com' // Notification email address
  orderId='0001' // Order ID
  serverIpn='serverIPN.com' // Server IPN
  sliderMax={250000} // Slider range maximum
  sliderMin={1} // Slider range minimum
  submitBtnText='Pay with' // Text on Button

  // === OPTIONAL Style Props ===

  // Default Input Field styles
  amountInputStyles={{
    MozAppearance: 'textfield',
    WebkitAppearance: 'textfield',
    appearance: 'textfield',
    border: 'none',
    boxShadow: 'none',
    textAlign: 'center',
    fontSize: '25px',
    margin: 'auto',
    marginBottom: 0,
    borderRadius: '5px',
    lineHeight: '35px',
    background: '#fff',
    color: '#000',
    width: '140px',
    maxWidth: '100%'
  }}

  // Default Form styles
  formStyles={{
    display: 'inline-flex',
    flexDirection: 'column',
    justifyContent: 'center',
    alignItems: 'center'
  }}

  // Default Plus/Minus Button styles
  plusMinusButtonStyles={{
    cursor: 'pointer',
    fontSize: '25px',
    lineHeight: '25px',
    color: '#000',
    background: '#DFE0E1',
    height: '30px',
    width: '45px',
    border: 'none',
    borderRadius: '60px',
    margin: 'auto 5px',
    display: 'inline-flex',
    justifyContent: 'center'
  }}

  // Default Range Slider styles
  rangeInputStyles={{
    MozAppearance: 'none',
    WebkitAppearance: 'none',
    appearance: 'none',
    width: '100%',
    background: 'transparent',
    marginTop: '10px',
    marginBottom: 0,
    outline: 0
  }}

  // Default Select (Dropdown) styles
  selectStyles={{
    MozAppearance: 'none',
    WebkitAppearance: 'none',
    appearance: 'none',
    color: 'currentColor',
    background: 'transparent',
    border: '1px solid',
    borderColor: 'transparent',
    display: 'block',
    padding: '1px',
    marginLeft: 'auto',
    marginRight: 'auto',
    marginBottom: '10px',
    fontSize: '11px',
    cursor: 'pointer'
  }}

  // Default Submit Button styles
  submitButtonStyles={{
    marginTop: '1rem',
    marginBottom: '2rem',
    minWidth: '168px',
    minHeight: '46px',
    borderRadius: '4px',
    backgroundColor: '#0f3b21',
    cursor: 'pointer',
    border: '2px solid transparent'
  }}

  // Default Submit Button Text styles
  submitButtonTextStyles={{
    color: '#fff',
    fontSize: '16px'
  }}
/>

Additional Resources

For more information about BTCPay Server or React, please refer to the BTCPay Server Documentation and React Documentation.

Contributing

Feel free to report issues, suggest features, and submit pull requests. See CONTRIBUTING.md for details.

Acknowledgements

Thank you to the teams behind React and BTCPay Server for providing the essential tools and frameworks used in this project.

License

This project is open-source and available under the MIT License.