Get started

Integrate MugglePay cryptocurrency payments into your website in minutes. This guide walks you through the complete setup process.

Overview

MugglePay provides a pre-built payment page and complete checkout experience that can be branded for your business. Integrate once and gain new features as MugglePay evolves.

Prerequisites

A website or application that needs to accept payments
Basic knowledge of HTTP APIs and webhooks
Access to your server's backend code

Integration Steps

Step 1: Register and Get API Key

Create Merchant Account
- Visit the Merchant Portal
- Sign up with your invitation code
- Complete your merchant profile

Get Your API Key
- Navigate to the API section in your dashboard
- Copy your unique API authentication token
- Keep this token secure - never expose it in client-side code

Learn more: Authentication Guide

Step 2: Integrate Payment Button

2.1 Add Payment Button

Choose from our pre-designed payment buttons or create your own:

2.2 Button Integration Example

<!-- Basic payment button -->
<button onclick="createPayment()" class="payment-btn">
  Pay with Crypto
</button>

<script>
async function createPayment() {
  try {
    const response = await fetch('/api/create-order', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        price_amount: 29.99,
        price_currency: 'USD',
        title: 'Premium Subscription'
      })
    });
    
    const result = await response.json();
    if (result.payment_url) {
      window.location.href = result.payment_url;
    }
  } catch (error) {
    console.error('Payment creation failed:', error);
  }
}
</script>

Step 3: Create Order API Integration

When a customer clicks the payment button, your backend should call the Create Order API:

Backend Implementation Example

// Node.js/Express example
app.post('/api/create-order', async (req, res) => {
  try {
    const orderData = {
      merchant_order_id: generateOrderId(),
      price_amount: req.body.price_amount,
      price_currency: req.body.price_currency,
      title: req.body.title,
      description: req.body.description,
      callback_url: 'https://yoursite.com/webhooks/payment',
      success_url: 'https://yoursite.com/success',
      cancel_url: 'https://yoursite.com/cart'
    };

    const response = await fetch('https://api.mugglepay.com/v1/orders', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'token': process.env.MUGGLEPAY_API_TOKEN
      },
      body: JSON.stringify(orderData)
    });

    const result = await response.json();
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: 'Order creation failed' });
  }
});

Step 4: Handle Payment Flow

4.1 Redirect to Payment Page

After successful order creation, redirect customers to the MugglePay payment page:

4.2 Payment Callback (Webhook)

Set up webhook handling to receive real-time payment notifications:

// Webhook endpoint example
app.post('/webhooks/payment', async (req, res) => {
  const { order_id, status, merchant_order_id } = req.body;
  
  if (status === 'PAID') {
    // Fulfill the customer's order
    await fulfillOrder(merchant_order_id);
  }
  
  res.status(200).send('OK');
});

Important: If you're not receiving webhook notifications, check:

Your callback_url is correctly set in the Create Order request
Your webhook endpoint is publicly accessible
Use the Merchant Portal to manually trigger callbacks for testing

Step 5: Testing and Validation

5.1 Test Your Integration

Create test orders with small amounts
Test the complete flow from button click to payment completion
Verify webhook notifications are received correctly
Test error scenarios (expired orders, cancellations)

5.2 Monitor in Merchant Portal

Track all transactions and orders in the Merchant Portal:

Complete Integration Example

Here's a minimal working example:

<!DOCTYPE html>
<html>
<head>
    <title>MugglePay Integration</title>
</head>
<body>
    <h1>Product Store</h1>
    <div class="product">
        <h2>Premium Subscription</h2>
        <p>Get access to all premium features</p>
        <p class="price">$29.99</p>
        <button onclick="buyProduct()">Buy Now</button>
    </div>

    <script>
        async function buyProduct() {
            try {
                // Create order on your backend
                const response = await fetch('/api/create-order', {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({
                        price_amount: 29.99,
                        price_currency: 'USD',
                        title: 'Premium Subscription',
                        description: 'Monthly premium access'
                    })
                });
                
                const result = await response.json();
                
                if (result.payment_url) {
                    // Redirect to MugglePay payment page
                    window.location.href = result.payment_url;
                } else {
                    alert('Failed to create order: ' + result.error);
                }
            } catch (error) {
                alert('Error: ' + error.message);
            }
        }
    </script>
</body>
</html>

Best Practices

✅ Do's

Test with small amounts before going live
Implement proper error handling
Use HTTPS for all API calls
Store API tokens securely
Monitor webhook delivery

❌ Don'ts

Don't expose API tokens in client-side code
Don't skip webhook validation
Don't assume payments will always succeed
Don't forget to handle edge cases

Troubleshooting

Common Issues

Webhook Not Receiving Notifications

Check URL accessibility: Ensure your webhook endpoint is publicly accessible
Verify callback_url: Make sure it's correctly set in Create Order requests
Test manually: Use the Merchant Portal to trigger test callbacks

Order Creation Fails

Check API token: Verify your authentication token is correct
Required fields: Ensure all required parameters are provided
Rate limits: Check if you've exceeded API rate limits

Payment Not Confirming

Network congestion: Some blockchain networks may be slow
Order expiry: Orders expire after 60 minutes (crypto) or 3 hours (fiat)
Contact support: Reach out if issues persist

Create Order API - Detailed API reference
Payment Callback - Webhook handling guide
Order Status - Understanding payment states
Authentication - API security guide
Error Codes - Common error solutions

Next Steps

Complete the integration following this guide
Test thoroughly with small amounts
Set up monitoring for your payment flow
Go live with real customers
Optimize based on usage patterns

Need Help?

Documentation: Browse our complete API reference
Support: Contact us through the Merchant Portal
Community: Join our developer community for tips and best practices

PreviousCustomer FAQ NextMerchant FAQ

Last updated 5 months ago

hashtagOverview

hashtagPrerequisites

hashtagIntegration Steps

hashtagStep 1: Register and Get API Key

hashtagStep 2: Integrate Payment Button

hashtag2.1 Add Payment Button

hashtag2.2 Button Integration Example

hashtagStep 3: Create Order API Integration

hashtagBackend Implementation Example

hashtagStep 4: Handle Payment Flow

hashtag4.1 Redirect to Payment Page

hashtag4.2 Payment Callback (Webhook)

hashtagStep 5: Testing and Validation

hashtag5.1 Test Your Integration

hashtag5.2 Monitor in Merchant Portal

hashtagComplete Integration Example

hashtagBest Practices

hashtag✅ Do's

hashtag❌ Don'ts

hashtagTroubleshooting

hashtagCommon Issues

hashtagWebhook Not Receiving Notifications

hashtagOrder Creation Fails

hashtagPayment Not Confirming

hashtagRelated Documentation

hashtagNext Steps

hashtagNeed Help?