Skip to content

fluidbase9/fluidwallet-pay

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
examples
examples
 
 
src
src
 
 
CHANGELOG.md
CHANGELOG.md
 
 
README.md
README.md
 
 
package.json
package.json
 
 

Repository files navigation

Fluid Wallet Pay

Accept crypto payments on your website in minutes.

npm version License: MIT

Fluid Wallet Pay is the easiest way to add a "Pay with Fluid Wallet" button to any website or app. When a customer clicks the button, a secure floating checkout card appears — they sign in with their Fluid Wallet, pick ETH or USDC, review the order, and confirm. Funds transfer directly on-chain to your merchant wallet. No intermediary. No KYC.

How it looks

┌─────────────────────────────────┐
│  ○ ○ ○ ○   Pay with Fluid Wallet│
│  Powered by Fluid Wallet        │
├─────────────────────────────────┤
│  Choose coin                    │
│                                 │
│  [Ξ] Ethereum  ETH   0.034 ETH  │
│  [$] USD Coin  USDC  210.00 USDC│
│                                 │
│  Order total  $89.00 USD        │
└─────────────────────────────────┘
         ↓ user picks ETH
┌─────────────────────────────────┐
│         $89.00                  │
│         0.035600 ETH            │
│  Pay with  Ξ ETH                │
│  From      0x1234...5678        │
│  To        Nova Store           │
│  Network fee  ~0.000315 ETH     │
│  Total     $89.50 USD           │
│  ┌────────────────────────────┐ │
│  │         Confirm            │ │
│  └────────────────────────────┘ │
└─────────────────────────────────┘
         ↓ confirmed on-chain
┌─────────────────────────────────┐
│  ✓  You sent $89.00             │
│     0.035600 ETH                │
│     To: 0xMer...chant           │
│  Tx: 0x4a5f...  □ ↗             │
│  ┌────────────────────────────┐ │
│  │           Done             │ │
│  └────────────────────────────┘ │
└─────────────────────────────────┘

Quick Start

Option 1 — Script tag (zero build step)

<!-- Add to <head> -->
<script src="https://js.fluidwallet.com/v1/pay.js"></script>

<!-- Payment button -->
<div id="fw-checkout"></div>

<script>
  FluidWalletPay.render('#fw-checkout', {
    apiKey: 'fw_live_YOUR_API_KEY',
    amount: 89.00,
    currency: 'USD',
    merchantWalletAddress: '0xYourMerchantAddress',
    merchantName: 'Nova Store',
    onSuccess: function(receipt) {
      console.log('Payment confirmed! Tx:', receipt.txHash);
      window.location.href = '/thank-you?tx=' + receipt.txHash;
    },
    onCancel: function() {
      console.log('Payment cancelled');
    }
  });
</script>

Option 2 — npm (React / Next.js)

npm install @fluidwallet/pay
import { FluidPayButton } from '@fluidwallet/pay/react';

export function CheckoutPage() {
  return (
    <FluidPayButton
      apiKey="fw_live_YOUR_API_KEY"
      amount={89.00}
      currency="USD"
      merchantWalletAddress="0xYourMerchantAddress"
      merchantName="Nova Store"
      onSuccess={(receipt) => {
        console.log('Paid!', receipt.txHash);
        router.push('/thank-you');
      }}
    />
  );
}

API Reference

FluidWalletPay.render(selector, options)

Option Type Required Description
apiKey string ✅ Your merchant API key from the Fluid Wallet dashboard
amount number ✅ Fiat amount to charge (e.g. 89.00)
currency string — Currency code, default "USD"
merchantWalletAddress string ✅ Your EVM wallet address that receives funds
merchantName string — Display name shown in the checkout
tokens string[] — Accepted tokens, default ["ETH", "USDC"]
onSuccess (receipt) => void — Called when payment is confirmed on-chain
onCancel () => void — Called when user closes without paying

PaymentReceipt object

interface PaymentReceipt {
  txHash: string;               // On-chain transaction hash
  amount: string;               // Crypto amount sent, e.g. "0.035600"
  symbol: string;               // Token symbol, e.g. "ETH"
  amountUsd: number;            // USD amount, e.g. 89.00
  currency: string;             // Currency code, e.g. "USD"
  merchantWalletAddress: string;
  timestamp: string;            // ISO-8601 timestamp
}

Webhook Events

Set up a webhook URL in your Merchant Dashboard → Webhooks tab to receive server-side payment notifications.

Event types

Event Description
payment.confirmed Transaction confirmed on-chain ✅ — safe to fulfill order
payment.pending Transaction broadcast, awaiting block confirmation
payment.failed Payment was not completed
payment.underpaid Customer sent less than requested

Payload

{
  "type": "payment.confirmed",
  "created": 1708810342,
  "data": {
    "paymentId": "pay_abc123",
    "orderId": "order_1708810300000",
    "amount": "89.00",
    "currency": "USD",
    "token": "ETH",
    "network": "ethereum",
    "txHash": "0x4a5f...",
    "fromAddress": "0xcustomer...",
    "toAddress": "0xmerchant...",
    "confirmedAt": "2026-02-24T02:31:51Z"
  }
}

Verifying webhook signatures

const FluidWalletPay = require('@fluidwallet/pay');

app.post('/webhooks/fluid', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-fluid-signature'];

  // Verify the signature using your webhook secret
  const isValid = FluidWalletPay.verifyWebhook(req.body, sig, process.env.FLUID_WEBHOOK_SECRET);
  if (!isValid) return res.status(400).send('Invalid signature');

  const event = JSON.parse(req.body);

  if (event.type === 'payment.confirmed') {
    fulfillOrder(event.data.orderId); // your business logic
  }

  res.json({ received: true });
});

Integration Examples

Shopify (manual liquid)

<!-- Add to your theme's checkout page -->
<div id="fw-checkout-{{ product.id }}"></div>
<script src="https://js.fluidwallet.com/v1/pay.js"></script>
<script>
  FluidWalletPay.render('#fw-checkout-{{ product.id }}', {
    apiKey: '{{ shop.metafields.fluidwallet.api_key }}',
    amount: {{ checkout.total_price | divided_by: 100.0 }},
    currency: '{{ shop.currency }}',
    merchantWalletAddress: '{{ shop.metafields.fluidwallet.wallet_address }}',
    merchantName: '{{ shop.name }}',
    onSuccess: function(r) { window.location.href = '/thank_you?tx=' + r.txHash; }
  });
</script>

WooCommerce (PHP)

function fluid_wallet_checkout_button() {
    $total = WC()->cart->get_total('edit');
    $api_key = get_option('fluid_wallet_api_key');
    $merchant_address = get_option('fluid_wallet_merchant_address');
    ?>
    <div id="fw-woo-checkout"></div>
    <script src="https://js.fluidwallet.com/v1/pay.js"></script>
    <script>
      FluidWalletPay.render('#fw-woo-checkout', {
        apiKey: '<?php echo esc_js($api_key); ?>',
        amount: <?php echo floatval($total); ?>,
        currency: 'USD',
        merchantWalletAddress: '<?php echo esc_js($merchant_address); ?>',
        onSuccess: function(r) { location.href = '<?php echo wc_get_checkout_url(); ?>?tx=' + r.txHash; }
      });
    </script>
    <?php
}
add_action('woocommerce_proceed_to_checkout', 'fluid_wallet_checkout_button');

Next.js App Router

// app/checkout/page.tsx
'use client';
import { FluidPayButton } from '@fluidwallet/pay/react';
import { useCart } from '@/hooks/useCart';

export default function CheckoutPage() {
  const { total, clearCart } = useCart();

  return (
    <div className="checkout-page">
      <h1>Checkout</h1>

      {/* Other payment methods */}
      <StripeButton />
      <PayPalButton />

      {/* Fluid Wallet Pay */}
      <FluidPayButton
        apiKey={process.env.NEXT_PUBLIC_FLUID_API_KEY!}
        amount={total}
        currency="USD"
        merchantWalletAddress={process.env.NEXT_PUBLIC_MERCHANT_WALLET!}
        merchantName="Your Store"
        onSuccess={async (receipt) => {
          // Save order to your database
          await fetch('/api/orders', {
            method: 'POST',
            body: JSON.stringify({ txHash: receipt.txHash, amount: receipt.amountUsd }),
          });
          clearCart();
          router.push('/order-confirmed');
        }}
      />
    </div>
  );
}

Supported Networks & Tokens

Network Token Status
Ethereum Mainnet ETH ✅ Live
Ethereum Mainnet USDC ✅ Live
Base ETH ✅ Live
Base USDC ✅ Live
Solana SOL 🔜 Coming soon
Solana USDC 🔜 Coming soon
Polygon MATIC 🔜 Coming soon

Getting Your API Key

  1. Go to app.fluidwallet.com → Login as Merchant
  2. Navigate to Merchant Console → Overview
  3. Click Generate API Key
  4. Copy fw_live_xxx... — keep it secret, never commit to source control

Security

  • Non-custodial: Funds transfer directly on-chain. Fluid Wallet never holds your funds.
  • No KYC: No sign-up required for customers. Any Fluid Wallet account can pay.
  • Seed phrase stays local: The customer's seed phrase is validated client-side and never transmitted.
  • Webhook signatures: Every webhook is signed with HMAC-SHA256. Always verify before fulfilling orders.
  • API key: Used only to identify your merchant account. Never use your wallet's private key or seed phrase as the API key.

REST API (Advanced)

For server-side integrations, you can create payment sessions directly:

Create a payment session

POST https://api.fluidwallet.com/v1/payments
Authorization: Bearer fw_live_YOUR_API_KEY
Content-Type: application/json

{
  "amount": 89.00,
  "currency": "USD",
  "orderId": "order_123",
  "redirectUrl": "https://yourstore.com/thank-you",
  "webhookUrl": "https://yourstore.com/webhooks/fluid"
}

Response:

{
  "paymentId": "pay_abc123",
  "checkoutUrl": "https://pay.fluidwallet.com/c/pay_abc123",
  "expiresAt": "2026-02-24T03:31:51Z"
}

Check payment status

GET https://api.fluidwallet.com/v1/payments/pay_abc123
Authorization: Bearer fw_live_YOUR_API_KEY

Changelog

See CHANGELOG.md

License

MIT © Fluid Wallet

About

Pay with Fluid Wallet — USDC payment SDK for Ethereum, Base & Solana. Accept crypto payments in minutes.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages