Checkout Integration
Embed XRP payments into any site or app with one API call. No SDK, no client-side script, no checkout UI to build - POST /payments/requests, get a pay_url, redirect or link your customer there. DropPay hosts the pay page.
Customers pay by scanning a QR code with any XRPL wallet. You receive a signed webhook when payment confirms on-chain. That is the entire integration.
Checkout is built for merchants. If you are a developer looking to monetize an API or accept programmatic payments, see the API payments use cases below.
How it works
POST /payments/requests creates a payment and returns two URLs:
| Field | Used by | Description |
|---|---|---|
pay_url |
Merchant / customer | Redirect the customer here. They pay via QR code. |
verify_url |
Developer / API | Called after sending XRP on-chain to confirm payment programmatically. |
The same payment.confirmed webhook fires regardless of how payment is completed.
Authentication
Request parameters
| Parameter | Type | Description |
|---|---|---|
amount |
float | Required. Amount in XRP or USD. |
currency |
string | "XRP" (default) or "USD". USD invoices convert to XRP at the live rate when the pay page opens. |
description |
string | Shown on the pay page. Max 256 characters. |
order_id |
string | Your order identifier. Returned in webhook and redirect. Max 128 characters. |
customer_id |
string | Your customer identifier. Returned in webhook. Max 128 characters. |
redirect_url |
string | Return URL after payment. Must be https://. DropPay appends ?request_id=&tx_hash=&order_id=. |
customer_name |
string | Pre-fills the name field on the pay page. |
customer_email |
string | Pre-fills email. DropPay emails a receipt on payment. |
expires_in_hours |
integer | Link lifetime in hours (1–8760). Checkout payments expire 30 minutes after the customer first opens the pay page. |
Use cases
Choose the one that fits your product:
Human payments
- Payment links - create a link and share it by email, message, or embed it as a button on your page. Simplest integration.
- E-commerce checkout - redirect a customer to pay mid-session, redirect them back to your site on success
- Pay-per-access - gate downloads or content behind a one-time payment
Programmatic payments
- API payments - accept per-request payments from AI agents or any HTTP client, no browser needed
- Payments on behalf of a user - complete a purchase for a pre-authorized user programmatically
Checkout vs x402
All checkout flows — including the programmatic ones — require your server to create the payment request first using your API key. The agent is told what to pay by your system. If you want agents to discover and pay your endpoint autonomously without any pre-created request, use x402 instead.
Redirect callback parameters
When a human payment confirms, DropPay redirects to your redirect_url with:
| Parameter | Description |
|---|---|
request_id |
DropPay payment ID |
tx_hash |
XRPL transaction hash |
order_id |
The order_id you passed at creation |
Never fulfill based on the redirect
Always fulfill from the webhook. The redirect URL can be crafted by anyone.