Skip to main content

​
Overview

Medusa Wallet integrates with Maxfy to enable seamless Bitcoin purchases directly within the app. You can buy Bitcoin using vouchers at competitive rates and receive the funds instantly in your Lightning wallet.
Bitcoin purchases are processed through Maxfy’s payment infrastructure and delivered directly to your Lightning address.

​
How It Works

The buy flow is designed to be simple and secure:
1

Select a voucher amount

Choose from available voucher denominations that fit your purchase needs
2

Verify your email

Use your account email or provide an alternative email for the purchase receipt
3

Complete checkout

Complete the payment through Stripe’s secure checkout interface
4

Receive Bitcoin

Bitcoin is delivered instantly to your Lightning address upon payment confirmation

​
Available Vouchers

The app displays active vouchers with the following information:
  • Amount: The Bitcoin value of the voucher
  • Fee: Processing fee charged by the payment provider
  • Total Price: Amount + fee displayed in your selected fiat currency
Vouchers are fetched in real-time from Maxfy’s API and only active vouchers are displayed.

​
Current Bitcoin Price

Before making a purchase, you can see the current Bitcoin price in your preferred fiat currency. The price is fetched from the Medusa pricing API and updated in real-time. 
// Example: Fetching current BTC price
const { data: btcPrice } = useQuery({
  queryKey: ['bitcoinPrice'],
  queryFn: () => medusa.getBitcoinPricesAt(Date.now())
})

// Display price in your fiat currency
const displayPrice = `${fiatUtils.getSymbol(fiatCurrency)}${formatNumber(btcPrice[fiatCurrency], 2)}`

​
Email Selection

You can choose which email to use for the purchase receipt:
Use the email associated with your Medusa Wallet account (default)
The email you provide will receive the purchase receipt and transaction details from the payment processor.

​
Payment Process

​
Creating a Transaction

When you select a voucher and continue to checkout: 
// Transaction creation from app/(authenticated)/(tabs)/buy.tsx
const createTransactionMutation = useMutation({
  mutationKey: ['createTransaction'],
  mutationFn: (addressUsername: string) =>
    maxfy.createTransaction(
      getPaylinkAddress(addressUsername),
      customerEmail,
      selectedVoucher
    ),
  onSuccess: async (data) => {
    // Checkout URL and transaction details returned
    setUri(data.checkout_url)
    setTxid(data.txid)
    setStripePrice(data.stripe_price)
  }
})

​
Secure Checkout

The payment is processed through Stripe’s secure WebView interface:
  • Transaction ID is generated and tracked
  • Payment information is securely transmitted
  • Cookies are set for session management
  • Bitcoin is delivered upon successful payment

​
Integration Details

​
Maxfy API

The buy feature integrates with the Maxfy API: Base URL: https://api.maxfy.app/v1 Available Methods:
  • getVouchers() - Fetches available active vouchers
  • createTransaction(lnaddress, email, voucherId) - Creates a purchase transaction
// From api/maxfy.ts
async function getVouchers() {
  const response = await fetch(`${API_URL}/vouchersGet`, {
    headers,
    method: 'GET'
  })
  const data = VouchersSchema.parse(await response.json())
  return data.vouchers.filter((voucher) => voucher.active)
}

async function createTransaction(
  lnaddress: string,
  email: string,
  voucherId: number
) {
  const response = await fetch(
    `${API_URL}/transactionAdd?lnaddress=${lnaddress}&email=${email}&voucher_id=${voucherId}`,
    {
      headers,
      method: 'POST'
    }
  )
  return CheckoutSchema.parse(await response.json())
}

​
Requirements

To use the Buy Bitcoin feature:
  • Active Medusa Wallet account
  • At least one wallet created
  • Lightning address configured (automatic with account creation)
  • Valid email address for receipt delivery

​
Troubleshooting

Vouchers may not be available if:
  • The Maxfy service is temporarily unavailable
  • Your region is not supported
  • No active vouchers are configured
Try refreshing the page or check back later.
If the payment fails during checkout:
  • No Bitcoin will be delivered
  • No charges will be made to your payment method
  • You can retry the purchase or contact support
Bitcoin is typically delivered to your Lightning address within seconds of payment confirmation. The payment is processed through the Lightning Network for instant settlement.
Yes, you can choose to use your account email or provide a different email address specifically for the purchase receipt. This is useful if you want receipts sent to a separate accounting or personal email.

Lightning Address

Learn more about your Lightning address

Wallet Management

Manage multiple wallets for organizing funds

Build docs developers (and LLMs) love

Get started for freeTalk to us