Sawfish Payments React Widget

A React payment widget for processing payments through the Sawfish API. Supports React 18.2+ and React 19+.

Installation

To install the package, run:

npm install sawfish-payment-react-widget

Version Compatibility

This package is compatible with:

• React 18.2+
• React 19+
• TypeScript 5.0+
• Node.js 16.0+

Usage

PaymentForm Component

The PaymentForm component is used to process payments through the Sawfish API.

Props

• environment (optional): The environment to use. Can be "production" or "staging".
• endpoint: The GraphQL endpoint. this plugin make use of GraphQL to communicate with the Sawfish API.
• apiSecret: The API secret.
• clientId: The client ID.
• amount: The payment amount.
• contact: The contact information.
• metadata (optional): Additional data to send to the server.
• onPaymentSuccess (optional): Callback function to handle successful payments.
• onPaymentError (optional): Callback function to handle payment errors.

Environment Variables

Create a .env file in your project root:

# Sawfish API Configuration

# For Next.js (use NEXT_PUBLIC_ prefix)
NEXT_PUBLIC_SAWFISH_ENVIRONMENT=staging
NEXT_PUBLIC_SAWFISH_ENDPOINT=https://api-staging.sawfish.com.au/graphql
NEXT_PUBLIC_SAWFISH_API_SECRET=your-api-secret-here
NEXT_PUBLIC_SAWFISH_CLIENT_ID=your-client-id-here

# For Create React App (use REACT_APP_ prefix)
# REACT_APP_SAWFISH_ENVIRONMENT=staging
# REACT_APP_SAWFISH_ENDPOINT=https://api-staging.sawfish.com.au/graphql
# NEXT_PUBLIC_SAWFISH_API_SECRET=your-api-secret-here
# REACT_APP_SAWFISH_CLIENT_ID=your-client-id-here

# For Vite (use VITE_ prefix)
# VITE_SAWFISH_ENVIRONMENT=staging
# VITE_SAWFISH_ENDPOINT=https://api-staging.sawfish.com.au/graphql
# NEXT_PUBLIC_SAWFISH_API_SECRET=your-api-secret-here
# VITE_SAWFISH_CLIENT_ID=your-client-id-here

Example ReactJs Component

import React from "react";
import { PaymentForm } from "sawfish-payment-react-widget";

const App = () => {
  const handlePaymentSuccess = (response: any) => {
    console.log("Payment successful:", response);
  };

  const handlePaymentError = (error: any) => {
    console.error("Payment error:", error);
  };

  return (
    <PaymentForm
      environment={process.env.NEXT_PUBLIC_SAWFISH_ENVIRONMENT || "staging"}
      endpoint={process.env.NEXT_PUBLIC_SAWFISH_ENDPOINT || ""}
      apiSecret={process.env.NEXT_PUBLIC_SAWFISH_API_TOKEN || ""}
      clientId={process.env.NEXT_PUBLIC_SAWFISH_CLIENT_ID || ""}
      amount={100}
      contact={{
        first_name: "John",
        last_name: "Doe",
        email: "[email protected]",
        country: "Australia",
      }}
      onPaymentSuccess={handlePaymentSuccess}
      onPaymentError={handlePaymentError}
      metadata={{
        // any additional data you want to send to the server
        // currently used to send the invoice id
        invoice_id: "1234",
      }}
    />
  );
};

export default App;

Environment Variables Best Practices

1. Security: Never commit your .env file to version control
2. Production: Use different environment variables for production and staging
3. Validation: Always validate that required environment variables are present
4. Fallbacks: Provide sensible defaults for optional variables
5. Framework Prefixes: Use the correct prefix for your framework:
   • Next.js: NEXT_PUBLIC_
   • Create React App: REACT_APP_
   • Vite: VITE_

Example Payment Response

{
    "amount": 604.72,
    "application_fee_amount": 11.08,
    "payment_gateway_fee": 11.08,
    "payment_at": "2025-03-04 00:00:00",
    "status": {
        "name": "payment_initiated"
    },
    "uuid": "...-...-...-...-..",
}

Development

To start the development server, run:

npm run dev

To build the package, run:

npm run build

To clean the build artifacts, run:

npm run clean

Publish

To publish the package, run:

npm run publish

License

The Sprint Sawfish payments plugin is open-sourced software licensed under the MIT license.