DropPay Documentation

DropPay is an XRP payment platform for freelancers, creators, developers, and businesses. Payments go directly to your XRPL wallet with no intermediaries. This documentation covers four core features: payment requests, the tip widget, the REST API, and AI agent payments with x402.

Overview

DropPay handles the payment infrastructure so you can focus on your work. You connect your XRP wallet once, then create payment requests, embed tip buttons, integrate via API, or charge AI agents per request. Every payment settles directly on the XRP Ledger, typically in 3 to 5 seconds.

Choose a section to get started:

Payment Requests
Create shareable payment links with QR codes and Xaman deep links.
Tip Widget
One script tag adds a Support Me button to any website.
API Integration
REST API with HMAC-signed webhooks for your application.
AI Agent Payments
x402 middleware charges AI agents per request over XRP.

Payment Requests

A payment request is a payment link you create for a specific amount. Share the link, show the QR code, or send the Xaman deep link. When your customer pays, DropPay detects the on-chain transaction and marks the request as paid.

Creating from the dashboard

  1. Log in and go to your Dashboard
  2. Click "New Payment Request"
  3. Enter the amount, currency (XRP or RLUSDComing soon), and an optional description and customer email
  4. Copy the pay_url or download the QR code and share it with your customer
  5. The payment appears in your dashboard the moment it confirms on the XRPL

What the customer sees

The pay_url opens a hosted payment page with the amount, a QR code, and a button to open in Xaman. Xaman is a free XRPL wallet app for iOS and Android. Your customer does not need a DropPay account.

Status and notifications

Payment status updates automatically. You can enable email notifications in Account settings. Pro plan accounts can configure a webhook URL to receive a POST request the moment payment confirms.

Minimum payment amount: 1 XRP. Payments go directly to your XRPL wallet. DropPay never holds your funds.

Tip Widget

The tip widget is an embeddable button that you can add to any website with a single script tag. Visitors can send you XRP without leaving your page, without creating an account, and without any setup on their end.

Adding the widget

Paste this script tag anywhere on your page:

<script src="https://droppayxrp.com/droppaytip.js" data-handle="yourhandle"> </script>

Replace yourhandle with your DropPay handle (visible in your dashboard under Account). The button appears wherever you place the script tag.

Configuration options

Attribute Description Default
data-handle Your DropPay handle (required) none
data-amount Pre-filled suggested amount none
data-currency XRP or RLUSDComing soon XRP
data-label Button label text "Support Me"
data-color Button hex color #2563EB
data-tab Open tip page in new tab instead of modal false

Where it works

Any HTML page: personal websites, WordPress, Ghost, Webflow, portfolio sites. If you can paste a script tag, it works.

The visitor does not need a DropPay account. They need an XRPL wallet such as Xaman (free on iOS and Android).

API Integration Pro

The DropPay REST API lets you create payment requests, retrieve payment status, and receive webhook notifications from your own application. This covers the most common integration pattern: a customer pays before getting access to something.

Authentication

All API requests require an API key in the Authorization header. Your key is available in your dashboard under Account. Keep it secret.

Authorization: Bearer dp_live_xxxxxxxxxxxxxxxxxxxx

Create a payment request

POST https://droppayxrp.com/payments/requests Authorization: Bearer dp_live_xxxxxxxxxxxxxxxxxxxx Content-Type: application/json { "amount": "25.00", "currency": "XRP", "description": "Order #1042", "customer_email": "buyer@example.com", "merchant_reference": "order_1042" }

Response:

{ "request_id": "dp_abc123", "pay_url": "https://droppayxrp.com/pay/dp_abc123", "status": "pending", "expires_at": "2026-06-12T10:00:00Z" }

Redirect or embed

Redirect your customer to pay_url or render the QR code on your own page by appending /qr to the pay_url. You can also use the Xaman deep link returned by the hosted page for mobile-first flows.

Webhooks

Configure a webhook URL in your dashboard. DropPay sends a POST request to your URL when a payment confirms.

{ "event": "payment.confirmed", "request_id": "dp_abc123", "amount": "25.00", "currency": "XRP", "xrpl_tx_hash": "ABCDEF...", "merchant_reference": "order_1042", "paid_at": "2026-06-11T14:22:00Z" }

Verify the webhook signature using the X-DropPay-Signature header:

import hmac, hashlib def verify_webhook(body: bytes, signature: str, secret: str) -> bool: expected = "sha256=" + hmac.new( secret.encode(), body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature)

Always verify the webhook signature before acting on a payment. The signature uses HMAC-SHA256 with your webhook secret.

Example: activate after payment

A typical ecommerce pattern: create the request when the customer checks out, redirect them to pay_url, and activate their order in your webhook handler.

@app.post("/webhook") async def payment_webhook(request: Request): body = await request.body() sig = request.headers.get("X-DropPay-Signature", "") if not verify_webhook(body, sig, WEBHOOK_SECRET): raise HTTPException(status_code=401) data = await request.json() if data["event"] == "payment.confirmed": activate_order(data["merchant_reference"]) return {"ok": True}

AI Agent Payments (x402) - Python

x402 is an open HTTP standard for per-request payments between machines. Add one middleware line to your FastAPI or Flask endpoint and it starts charging AI agents automatically, per request, with no billing accounts or subscriptions on either side. Payment goes from the agent wallet to your wallet, directly on the XRP Ledger. Python frameworks FastAPI and Flask are supported at the moment.

x402 for XRP is live and tested on XRPL mainnet. RLUSDComing soon support is coming soon.

How x402 works

  1. An AI agent (or any HTTP client) calls your endpoint without paying
  2. Your endpoint returns HTTP 402 with your wallet address, price, and the DropPay verification URL
  3. The client pays the exact amount to your wallet on the XRP Ledger
  4. The client retries the original request with X-Payment: txhash in the header
  5. The middleware calls DropPay to verify the transaction on-chain
  6. If valid, the request passes through. The agent gets its data.

Setting up the middleware

pip install droppay-x402 --extra-index-url https://droppayxrp.com/pypi/simple/

Enable x402 in your DropPay dashboard and copy your config URL. Then add the middleware:

FastAPI:

from droppay_x402 import DropPayX402Middleware app.add_middleware( DropPayX402Middleware, config_url="https://droppayxrp.com/x402/config/yourhandle", protected_paths=["/api/data"] # optional: protect specific paths only )

Flask:

from droppay_x402 import FlaskDropPayX402 app.wsgi_app = FlaskDropPayX402( app.wsgi_app, config_url="https://droppayxrp.com/x402/config/yourhandle" )

Set your price and currency in your DropPay dashboard under Account settings. XRP is live. RLUSDComing soon support is coming soon.

Setting up your agent wallet

Before your agent can pay, it needs an XRPL wallet funded with XRP. If you are new to agentic transactions on the XRP Ledger, follow Ripple's official guide to create a wallet, fund it on testnet, and confirm your first transaction before going to mainnet.

Required reading: Getting Started with Agentic Transactions on XRPL covers wallet creation, funding, and your first autonomous payment on the XRP Ledger.

Paying as an agent (X402Client)

If you are building an AI agent or automated service that calls x402-protected APIs, the X402Client handles payment automatically:

import os from droppay_x402 import X402Client # The client handles 402 -> pay -> retry transparently client = X402Client(wallet_seed=os.environ["XRPL_SEED"]) response = client.get("https://api.example.com/data") print(response.json())

Install:

pip install "droppay-x402[client]" --extra-index-url https://droppayxrp.com/pypi/simple/

Fund your agent wallet with XRP using Xaman. The X402Client warns you when the balance drops below a configurable threshold.

Pricing and verification

Set any XRP amount as your price from the dashboard. The minimum is 1 XRP. DropPay verifies each transaction on the XRP Ledger before granting access. Replay protection is built in: each transaction hash can only be used once.

DropPay verifies payments but never holds your funds. Money goes from the agent wallet to your wallet directly. Settlement takes 3 to 5 seconds on the XRP Ledger.

Use cases

x402 works for any API that provides data or computation on demand:

  • Financial data, market prices, research summaries
  • LLM inference and AI model endpoints
  • Translation, classification, and analysis services
  • Real-time sensor data from IoT devices
  • Any service where per-request pricing makes more sense than a subscription

MCP server for Claude

DropPay also ships a Model Context Protocol server that connects your DropPay account to Claude Desktop. Install it separately:

pip install "droppay-x402[mcp]" --extra-index-url https://droppayxrp.com/pypi/simple/

Configure it in your Claude Desktop MCP settings with your dp_live_ API key. The MCP server requires a Pro account. Once connected, ask Claude to create payment requests, check invoice status, or list recent payments.

AI Agent Payments JavaScript

The same x402 flow is available for Node.js servers via a single downloadable script. No npm, no package manager. Download the file once, require() it, and any Express, Fastify, Next.js, or vanilla Node.js endpoint starts charging per request. All verification still runs on DropPay's backend — your server never touches the XRP Ledger directly.

Important Note: Known limitations
  • Requires Node.js 18 or higher that uses native fetch, which is not available in older Node versions
  • Does not support edge runtimes, Cloudflare Workers, Vercel Edge Functions, and Deno are not compatible
  • No TypeScript types included which means you will need to add your own type declarations or cast manually
  • No auto-updates. Devs must re-download the file manually to get future changes made to code. Future versions will be part of npm.

Download

curl -O https://droppayxrp.com/droppay402.js

Or copy the file URL directly into your project: Download Droppay402.js. Place it anywhere in your project and require it by path.

Express

Pass the middleware to any route or router. The middleware checks for an X-Payment header. If missing, it returns 402 with your price and wallet. If present, it verifies the transaction and calls next().

const express = require('express') const { droppay402 } = require('./droppay402.js') const app = express() app.get('/api/data', droppay402({ handle: 'yourhandle' }), (req, res) => { res.json({ data: 'protected content' }) })

Next.js — App Router (middleware.js)

// middleware.js (project root) import { droppay402Next } from './droppay402.js' export const middleware = droppay402Next({ handle: 'yourhandle' }) export const config = { matcher: ['/api/data/:path*'] }

Next.js — pages/api route

// pages/api/data.js const { droppay402Handler } = require('../../droppay402.js') export default droppay402Handler({ handle: 'yourhandle' }, (req, res) => { res.json({ data: 'protected content' }) })

Fastify

const fastify = require('fastify')() const { droppay402Fastify } = require('./droppay402.js') fastify.addHook('preHandler', droppay402Fastify({ handle: 'yourhandle' })) fastify.get('/api/data', async (request, reply) => { return { data: 'protected content' } })

Vanilla Node.js

Use verify402 directly and write the response yourself — works with any HTTP framework or the built-in http module.

const http = require('http') const { verify402 } = require('./droppay402.js') http.createServer(async (req, res) => { if (req.url !== '/api/data') return res.end() const result = await verify402({ handle: 'yourhandle' }, req.headers) if (!result.paid) { res.writeHead(402, { 'Content-Type': 'application/json' }) res.end(JSON.stringify(result.body || { error: result.error })) return } res.writeHead(200, { 'Content-Type': 'application/json' }) res.end(JSON.stringify({ data: 'protected content' })) }).listen(3000)

Set your price and currency in your DropPay dashboard under Account settings. The JS file reads your config automatically, no code change needed when you update your price.