Embedded Checkout Integration Guide

Embedded Checkout is DropPay's API-based payment integration. It lets you add XRP payment acceptance to any website, store, or application. Customers check out on a DropPay-hosted pay page and return to your site after payment confirms. Your server receives a webhook when the payment is verified. The same integration also handles payments from AI agents using the x402 protocol.

This guide covers the full integration: creating payment requests, handling the post-payment redirect, setting up webhooks, and testing before going live.

Embedded Checkout vs Payment Links

Before integrating, confirm that Embedded Checkout is the right tool for your use case.

Use Embedded Checkout when you need automated fulfillment based on payment confirmation, your payment amounts are dynamic (set per transaction), you want customers to return to your site after payment, or you need to support AI agent payments alongside human customers.

Use Payment Links when the payment amount is fixed or set manually per invoice, you do not have a website or developer available, or you are invoicing clients and sharing a link via email or messaging. Payment Links require no code and no backend integration. See Payment Links for more.

Prerequisites

• A DropPay Pro account with your XRP wallet address configured in Settings. Pro is required for API access and webhooks.
• Your API key from the dashboard (Settings > API Keys).
• A server-side backend that can make HTTP requests and receive webhooks over HTTPS.

The full API reference is in the developer documentation. All examples below show the endpoint and parameters. Code examples for JavaScript, Python, and other languages are available in the docs.

Step 1: Create a payment request

When a customer is ready to pay, your server creates a payment request via the DropPay API. The request specifies the amount, currency, and where to send the customer after payment.

The endpoint is POST /payments/requests. The required parameters are the amount, the currency (USD), and a redirect URL for after payment completes. Optional parameters include a webhook URL and order reference metadata.

DropPay converts the amount to XRP at the current rate and returns a payment request ID and a pay page URL. Redirect your customer to that URL to begin checkout.

Step 2: Customer pays on the pay page

The pay page at /pay/{id} shows the customer the XRP amount, a QR code, and a Xaman wallet button. The page monitors the XRP Ledger in real time and detects payment automatically when the transaction confirms, typically within 3 to 5 seconds of the customer sending XRP.

After payment confirms, the customer is redirected to the URL you specified in the payment request.

Step 3: Handling the redirect

The redirect URL receives the customer with a payment_id query parameter. At this point, the payment may still be in the verification process. Do not use the redirect alone to grant access or fulfill an order. Use the webhook instead.

The redirect is for UX - return the customer to a confirmation page that tells them their payment is processing. Your webhook handler is where fulfillment logic belongs.

Step 4: Set up your webhook handler

DropPay fires a POST request to your webhook URL when a payment is confirmed on the XRP Ledger. The webhook payload includes the payment ID, status, amount, XRP transaction hash, and the caller's wallet address.

Your webhook handler should:

1. Verify the webhook signature using your API key to confirm the request is from DropPay.
2. Check that the payment status is confirmed.
3. Use the payment ID to look up the corresponding order in your system.
4. Mark the order as paid and trigger fulfillment.
5. Return HTTP 200 to acknowledge receipt. DropPay retries webhooks that do not receive a 200 response.

The webhook schema and signature verification method are covered in the documentation.

Supporting AI agent payments

The same Embedded Checkout integration handles AI agent payments. The difference is in how the client interacts with the payment flow.

Human customers follow the redirect to the pay page, use a wallet, and are redirected back. AI agents do not open browsers. They call POST /payments/requests directly, retrieve the payment specification, send XRP on-chain, and call POST /payments/{id}/verify with the transaction hash.

Your server does not need to handle agents differently. The same payment request, the same webhook, and the same fulfillment logic apply. If you also want to implement x402 (HTTP 402 responses so agents can discover payment requirements before attempting access), the x402 guide covers that separately.

Testing your integration

Before going live, test the full payment flow:

• Create a payment request with a small test amount.
• Complete the payment using a test XRP wallet or Xaman in testnet mode.
• Confirm your webhook receives the confirmation event with the correct payload.
• Confirm the redirect delivers the customer to your success page with the payment ID.
• Confirm your fulfillment logic triggers correctly based on the webhook event.

Test with both the human pay page flow and the programmatic API flow if you plan to support AI agents.

Go-live checklist

• XRP wallet address confirmed in Settings and receiving test payments correctly.
• Webhook URL is publicly accessible over HTTPS.
• Webhook signature verification is implemented and tested.
• Webhook handler is idempotent.
• Redirect URL returns the customer to a meaningful confirmation page.
• Fulfillment is triggered by webhook, not by redirect.
• Error handling is in place for cases where webhook delivery is delayed.

Frequently asked questions

What happens if a customer pays the wrong amount? DropPay checks the transaction amount against the payment request. Underpayments are not confirmed. Overpayments are confirmed and the full received amount is recorded. Handle overpayments in your application layer based on your refund policy.

How long is a payment request valid? Payment requests expire after a configurable window (default: 15 minutes). If the customer does not pay within that window, the request expires and a new one must be created. The expiry time can be set per-request in the API. See the documentation for the parameter name and valid range.

Can I use Embedded Checkout without webhooks? The redirect delivers a payment ID that you can use to poll the payment status endpoint. However, webhooks are the recommended approach. Polling introduces latency and requires your frontend to handle the verification loop. Webhooks are more reliable and simpler to implement correctly.

Where do I find my API key? In your DropPay dashboard under Settings > API Keys. Pro plan is required. Keep your API key server-side only. Never expose it in client-side code or public repositories.

For a broader overview of what Embedded Checkout enables, see the Embedded Checkout feature page. For the complete API reference, refer to the developer documentation.