Human-approved x402 payments on XRPL

Use Ondex for explicit XRP or RLUSD payment review while your page keeps ownership of its request, cookies, authorization, body, CORS policy, and protected resource.

Quick start Markdown contract

Use the explicit SDK wrapper

Install @ondex/[email protected] and call ondexX402Fetch directly inside a click or submit handler. A compatible provider must report x402 support at runtime. The helper never patches global fetch and performs at most one paid retry.

GET uses the same wrapper without a body. POST preserves caller headers, credentials, and replayable bodies. Streaming bodies, HEAD, OPTIONS, prerender, cross-origin paid redirects, and automatic second payments are blocked.

import { ondexX402Fetch } from '@ondex/dapp-client';

button.addEventListener('click', async () => {
  const response = await ondexX402Fetch('/api/report', {
    method: 'POST',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ topic: 'XRPL' }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
});

Expose the protocol headers through CORS

The merchant allows PAYMENT-SIGNATURE as a request header and exposes PAYMENT-REQUIRED plus PAYMENT-RESPONSE as response headers.

Do not send Access-Control-Expose-Headers as a request header. HttpOnly cookies stay browser-owned and are never copied to Ondex.

Access-Control-Allow-Origin: https://your-dapp.example
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Authorization, Content-Type, PAYMENT-SIGNATURE
Access-Control-Expose-Headers: PAYMENT-REQUIRED, PAYMENT-RESPONSE

One flow, three independent outcomes

Authorization

The user approves one exact, expiring XRPL transaction. Once exposed, the signed blob may be submitted until ledger expiry.

Settlement

Payment is confirmed only when the exact expected hash is validated with tesSUCCESS and the destination, asset or issuer, and delivered amount match. A validated tec* is a fee-charged failure.

Resource

The merchant response is separate. HTTP 200 does not prove payment, and a confirmed payment can still have a service-delivery failure.

Run the Foundation-compatible merchant fixture

The fixture pins Foundation packages to 2.21.0, initializes the official resource server, registers ExactXrplScheme, and protects GET, POST, and handler-failure routes.

It is Testnet-only and requires a public testnet payee address. The example uses the external x402.org facilitator only after its live /supported response advertises exact x402 V2 for xrpl:1. It contains no wallet seed or facilitator key.

curl https://x402.org/facilitator/supported
# Confirm an exact x402 V2 entry for xrpl:1, then:
cd ondex-dapp-client
FACILITATOR_URL=https://x402.org/facilitator \
XRPL_PAYEE_ADDRESS=rTestnetMerchantAddress \
pnpm example:x402-merchant

# GET and POST protected resources
curl -i http://localhost:4021/paid/report
curl -i -X POST -H 'Content-Type: application/json' -d '{"topic":"XRPL"}' http://localhost:4021/paid/report

Failures never authorize another payment automatically

A second 402 is returned as a new review requirement.
CORS/network errors, missing or malformed settlement headers, and post-authorization HTTP errors enter exact-hash reconciliation.
Verification or settlement failure never serves the protected resource.
If payment validates but service delivery fails, show the transaction hash for support and do not offer Pay again.

Security boundary

Ondex signs on the user's device and never gives the merchant wallet keys. The merchant chooses and trusts its facilitator and must verify its advertised network support at runtime. Never log signed blobs, send page cookies or Authorization headers to Ondex, or treat UI approval as confirmed payment.