Integration Guide

Add crypto payments to any website in minutes. Works with Shopify, WooCommerce, custom sites, or any platform.

Universal HTML Snippet

Copy and paste this single script tag into any website. It creates a "Pay with Crypto" button that opens the GroundedPay checkout modal.

Quick Start (Inline Button)

<script src="https://groundedpay.com/embed.js"
        data-merchant-id="YOUR_MERCHANT_ID"
        data-amount="49.99"
        data-currency="USD"
        data-order-id="order-123"></script>

The button renders right where you place the script tag. When clicked, it opens a checkout modal overlay.

Floating Button Mode

Add data-button-style="floating" to show a fixed-position button in the bottom-right corner of the page:

<script src="https://groundedpay.com/embed.js"
        data-merchant-id="YOUR_MERCHANT_ID"
        data-amount="49.99"
        data-button-style="floating"
        data-button-text="Pay with Crypto"></script>

Place Button in a Specific Container

Use data-button-position with a CSS selector to inject the button into a specific element:

<div id="crypto-pay-container"></div>

<script src="https://groundedpay.com/embed.js"
        data-merchant-id="YOUR_MERCHANT_ID"
        data-amount="49.99"
        data-button-position="#crypto-pay-container"></script>

Configuration Attributes

AttributeDefaultDescription
data-merchant-idRequiredYour GroundedPay merchant ID
data-amountRequiredPayment amount (e.g., "49.99")
data-currencyUSDCurrency code
data-order-id--Your order/invoice ID for tracking
data-callback-url--Webhook URL to call when payment confirms
data-success-url--Redirect URL after successful payment
data-button-textPay with CryptoButton label
data-button-styleinlineinline or floating
data-button-color#6366f1Button background color
data-button-text-color#ffffffButton text color
data-button-position--CSS selector to inject button into
data-gateway-urlhttps://groundedpay.comOverride for self-hosted gateways

JavaScript API

After the embed script loads, you can use the window.GroundedPay object for programmatic control:

// Trigger a payment programmatically
GroundedPay.pay({
  amount: 49.99,
  currency: 'USD',
  orderId: 'order-456',
  callbackUrl: 'https://yoursite.com/webhook',
  successUrl: 'https://yoursite.com/thank-you',
  onCreated: function(data) { console.log('Payment created:', data.payment_id); },
  onError: function(err) { console.error('Error:', err.message); }
});

// Render a button into a specific container
GroundedPay.renderButton(document.getElementById('pay-here'), {
  amount: 29.99,
  buttonText: 'Buy Now with Crypto',
  buttonColor: '#22c55e'
});

// Close the checkout modal
GroundedPay.close();

// Listen for confirmed payments
window.addEventListener('groundedpay:confirmed', function(e) {
  console.log('Payment confirmed:', e.detail.payment_id);
});

CSS Customization

Override button styles with CSS using the .groundedpay-btn class:

.groundedpay-btn {
  border-radius: 4px !important;
  font-size: 14px !important;
  padding: 12px 20px !important;
}

Shopify Integration

For Shopify stores, use the dedicated Shopify embed that automatically detects cart totals and injects the button next to your checkout button.

Setup (5 minutes)

  1. Go to your Shopify admin → Online StoreThemesEdit Code
  2. Open theme.liquid
  3. Paste this snippet just before the closing </body> tag:
<script src="https://groundedpay.com/embed-shopify.js"
        data-merchant-id="YOUR_MERCHANT_ID"></script>

The script automatically:

Shopify Configuration Options

AttributeDefaultDescription
data-merchant-idRequiredYour GroundedPay merchant ID
data-button-textPay with CryptoButton label
data-button-color#6366f1Button background color
data-button-text-color#ffffffButton text color
data-button-positionafter-checkoutafter-checkout, before-checkout, or custom:#selector
Shopify Script Tag API: You can also install the embed via Shopify's Script Tag API for automatic injection across all pages. Contact support@groundedpay.com for setup help.

WooCommerce Integration

Add crypto payments to your WooCommerce store by embedding the universal snippet in your theme.

Option 1: Theme Editor (Simplest)

  1. In WordPress admin, go to AppearanceTheme Editor
  2. Open footer.php
  3. Add this snippet before </body>:
<script src="https://groundedpay.com/embed.js"
        data-merchant-id="YOUR_MERCHANT_ID"
        data-button-style="floating"
        data-button-text="Pay with Crypto"></script>

<!-- Set amount dynamically from WooCommerce cart -->
<script>
document.addEventListener('DOMContentLoaded', function() {
  // Read cart total from WooCommerce checkout page
  var totalEl = document.querySelector('.order-total .amount') ||
                document.querySelector('.cart-subtotal .amount');
  if (totalEl) {
    var amount = parseFloat(totalEl.textContent.replace(/[^0-9.]/g, ''));
    if (amount > 0 && window.GroundedPay) {
      // Remove the auto-generated floating button
      var autoBtn = document.querySelector('.groundedpay-btn');
      if (autoBtn) autoBtn.remove();

      // Render button with correct amount next to checkout
      var target = document.querySelector('.wc-proceed-to-checkout') ||
                   document.querySelector('#place_order').parentElement;
      if (target) {
        GroundedPay.renderButton(target, {
          amount: amount,
          orderId: document.querySelector('input[name="order_id"]')?.value
        });
      }
    }
  }
});
</script>

Option 2: functions.php (Recommended)

Add this to your theme's functions.php for cleaner integration:

// Add GroundedPay crypto payments
add_action('wp_footer', function() {
  if (is_checkout() || is_cart()) {
    $total = WC()->cart->get_total('edit');
    echo '<script src="https://groundedpay.com/embed.js"
            data-merchant-id="YOUR_MERCHANT_ID"
            data-amount="' . esc_attr($total) . '"
            data-button-position=".wc-proceed-to-checkout"
            data-button-text="Pay with Crypto"></script>';
  }
});
Dynamic amounts: WooCommerce updates cart totals via AJAX. For the best experience, use the REST API approach (see API tab) and update the amount when the cart changes.

Custom Website Integration

For any custom-built website or web app, you have full flexibility.

Basic: Static Amount

If you know the amount at page load (e.g., a product page with a fixed price):

<!-- Place this where you want the button -->
<div id="pay-button"></div>

<script src="https://groundedpay.com/embed.js"
        data-merchant-id="YOUR_MERCHANT_ID"
        data-amount="99.99"
        data-order-id="INV-2024-001"
        data-callback-url="https://yoursite.com/api/payment-webhook"
        data-success-url="https://yoursite.com/thank-you"
        data-button-position="#pay-button"></script>

Dynamic: Set Amount from JavaScript

Calculate the amount at runtime (e.g., shopping cart, dynamic pricing):

<!-- Load the embed (no data-amount = no auto-button) -->
<script src="https://groundedpay.com/embed.js"
        data-merchant-id="YOUR_MERCHANT_ID"></script>

<div id="checkout-area"></div>

<script>
// Calculate amount from your cart/order
var cartTotal = calculateCartTotal(); // your function

// Render button with dynamic amount
GroundedPay.renderButton(document.getElementById('checkout-area'), {
  amount: cartTotal,
  orderId: 'order-' + Date.now(),
  callbackUrl: 'https://yoursite.com/api/payment-webhook',
  successUrl: 'https://yoursite.com/thank-you',
  buttonText: 'Pay $' + cartTotal.toFixed(2) + ' with Crypto'
});

// Or trigger payment directly from your own button:
document.getElementById('my-pay-btn').addEventListener('click', function() {
  GroundedPay.pay({
    amount: cartTotal,
    orderId: 'order-' + Date.now(),
    callbackUrl: 'https://yoursite.com/api/payment-webhook',
    successUrl: 'https://yoursite.com/thank-you'
  });
});
</script>

Webhook Handler Example (Node.js)

// Express webhook handler
app.post('/api/payment-webhook', (req, res) => {
  const { event, payment_id, status, amount, order_id, tx_hash } = req.body;

  if (event === 'payment.confirmed') {
    // Mark order as paid in your database
    db.markOrderPaid(order_id, {
      paymentId: payment_id,
      txHash: tx_hash,
      amount: amount
    });

    // Send confirmation email, fulfill order, etc.
    sendConfirmationEmail(order_id);
  }

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

REST API Reference

For headless / server-to-server integrations, use the REST API directly. No JavaScript embed needed.

Base URL: https://groundedpay.com

POST /api/payments/create

Create a new crypto payment.

Request Body

{
  "amount": 49.99,
  "currency": "USD",
  "merchant_id": "YOUR_MERCHANT_ID",
  "order_id": "order-123",
  "callback_url": "https://yoursite.com/webhook",
  "coin": "usdc"
}
FieldTypeDescription
amountnumberRequired Payment amount
currencystringCurrency code (default: "USD")
merchant_idstringRequired Your merchant ID
order_idstringYour order/invoice ID
callback_urlstringWebhook URL for payment confirmation
coinstringCrypto: "usdc" (default), "usdt", "eth", "btc"

Response

{
  "payment_id": "a1b2c3d4-...",
  "status": "pending",
  "coin": "usdc",
  "chain": "base",
  "amount": 49.99,
  "currency": "USD",
  "amount_crypto": "49.99",
  "payment_address": "0x...",
  "qr_code": "data:image/png;base64,...",
  "qr_uri": "ethereum:0x...@8453?value=49.99",
  "expires_at": "2026-04-12T12:00:00.000Z",
  "checkout_url": "https://groundedpay.com/checkout.html?payment=a1b2c3d4-..."
}
Tip: Use the checkout_url to redirect customers to a hosted checkout page, or build your own UI using the payment_address and qr_code.
GET /api/payments/:id/status

Check the status of a payment.

Response

{
  "payment_id": "a1b2c3d4-...",
  "status": "confirmed",
  "coin": "usdc",
  "chain": "base",
  "amount": 49.99,
  "currency": "USD",
  "amount_crypto": "49.99",
  "payment_address": "0x...",
  "order_id": "order-123",
  "tx_hash": "0xabc...",
  "confirmations": 12,
  "confirmed_at": "2026-04-12T11:35:00.000Z"
}

Payment Statuses

StatusDescription
pendingAwaiting payment
detectedTransaction seen on chain, awaiting confirmations
confirmedPayment confirmed on blockchain
expiredPayment window expired (no transaction received)

Webhook Callbacks

When a payment is confirmed, GroundedPay sends a POST request to your callback_url:

POST https://yoursite.com/webhook
Content-Type: application/json

{
  "event": "payment.confirmed",
  "payment_id": "a1b2c3d4-...",
  "status": "confirmed",
  "amount": 49.99,
  "currency": "USD",
  "coin": "usdc",
  "chain": "base",
  "amount_crypto": "49.99",
  "tx_hash": "0xabc...",
  "order_id": "order-123",
  "confirmed_at": "2026-04-12T11:35:00.000Z",
  "timestamp": "2026-04-12T11:35:01.000Z"
}

cURL Examples

Create a Payment

curl -X POST https://groundedpay.com/api/payments/create \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "merchant_id": "YOUR_MERCHANT_ID",
    "order_id": "order-123",
    "callback_url": "https://yoursite.com/webhook"
  }'

Check Payment Status

curl https://groundedpay.com/api/payments/PAYMENT_ID/status

Legacy Shopify API

The original Shopify-specific endpoints remain available for backward compatibility:

How It Works

Non-custodial. Crypto payments go directly to the wallet address you configure in your GroundedPay dashboard. We never hold your funds.
  1. Your website loads the GroundedPay embed script (or calls the API).
  2. When the customer clicks "Pay with Crypto," a payment is created via the API with the amount and order details.
  3. A modal overlay (or hosted checkout page) shows the payment address and QR code.
  4. GroundedPay monitors the blockchain for the incoming transaction.
  5. Once confirmed, the modal closes, the customer sees a success message (or is redirected), and your webhook is called.

Testing

Use your dashboard to monitor incoming payments in real time. Payments auto-refresh every 30 seconds.

Need help? Contact us at support@groundedpay.com