XRPayDocs
SupportStart free
Home›Documentation›Developer SDK
SDK v1.0.0Non-Custodial

Developer SDK & Elements

Accept XRP, RLUSD, and custom XRPL token payments on any website or application. Use our UMD/ESM JavaScript SDK, custom Web Components, or React Hooks.

Quick Start

Integrate XRPay payments into your checkout flow in three simple steps.

1

Retrieve API Keys

Sign in to your dashboard, navigate to **Settings > API Keys**, and generate your publishable key (pk_test_* or pk_live_*).

2

Include the Client Library

Add the XRPay UMD library script tag directly to the header of your HTML checkout page.

html
<script src="https://xrpay.it/sdk/xrpay.js"></script>
3

Initialize and Redirect

Instantiate XRPay with your key and create a session. Redirect the user to the returned checkout URL.

javascript
// Initialize the SDK
const xrpay = XRPay('pk_test_your_publishable_key');

// Trigger on checkout button click
document.getElementById('checkout-button').addEventListener('click', async () => {
  const session = await xrpay.sessions.create({
    amount: 19.99,
    currency: 'USD',
    successUrl: window.location.origin + '/success',
    cancelUrl: window.location.origin + '/cancel',
  });

  // Redirect to hosted checkout
  xrpay.redirectToCheckout({ sessionId: session.id });
});

JavaScript SDK Reference

The client library includes methods for opening checkout sheets, handling popups, and monitoring payment status.

Alternative: Open Checkout in Popup

If you prefer to keep customers on your site, you can launch the checkout session in an overlay popup instead of a redirect.

javascript
// Create session and open checkout in a popup overlay
const session = await xrpay.sessions.create({ amount: 15.00, currency: 'USD' });
xrpay.openPopup({ 
  sessionId: session.id,
  onClose: () => console.log('Popup checkout window was closed')
});

Real-Time Status Monitoring

Subscribe to checkout session status changes. The callback triggers automatically when payments are validated on-ledger.

javascript
// Poll status updates and trigger success behaviors
xrpay.sessions.onStatusChange(session.id, (status) => {
  if (status.status === 'confirmed') {
    alert('Payment successful! Transaction Hash: ' + status.txHash);
    window.location.href = '/success';
  } else if (status.status === 'expired') {
    alert('Payment checkout session expired.');
  }
});

Web Components (Elements)

Build responsive, drop-in payment interfaces using framework-agnostic HTML Custom Elements. Includes built-in support for light/dark themes and styling customization.

html
<script src="https://xrpay.it/sdk/xrpay-elements.js"></script>

<!-- Embedded payment buttons -->
<xrpay-button
  api-key="pk_test_..."
  amount="49.99"
  currency="USD"
  label="Pay with XRPay"
  theme="light">
</xrpay-button>

<!-- Full embedded inline checkout UI with countdown & QR code -->
<xrpay-checkout
  api-key="pk_test_..."
  amount="150.00"
  currency="USD"
  settlement-currency="RLUSD">
</xrpay-checkout>

<!-- Mini inline payment status indicator badge -->
<xrpay-status
  api-key="pk_test_..."
  session-id="cmr2o3ink000ayk43f5rodogr">
</xrpay-status>

Custom Custom-Elements Event Hooks

Web components dispatch custom events during checkout lifecycles so you can capture updates in your local application state.

javascript
// Listen for successful on-chain validation
document.querySelector('xrpay-checkout').addEventListener('xrpay:payment-confirmed', (e) => {
  const { txHash, amount, currency } = e.detail;
  console.log(`Received ${amount} ${currency}. Tx: ${txHash}`);
});

// Listen for session expiration
document.querySelector('xrpay-checkout').addEventListener('xrpay:payment-expired', (e) => {
  console.warn('Checkout expired:', e.detail.sessionId);
});

React SDK & Hooks

Integrate natively in React applications using hooks and contextual state providers.

jsx
import { XRPayProvider, useXRPay, usePaymentStatus, XRPayButton } from 'https://xrpay.it/sdk/xrpay-react.js';

function App() {
  return (
    <XRPayProvider apiKey="pk_test_...">
      <CheckoutPage />
    </XRPayProvider>
  );
}

function CheckoutPage() {
  const { createSession, redirectToCheckout, isLoading } = useXRPay();

  const handlePayment = async () => {
    const session = await createSession({ amount: 99.00, currency: 'USD' });
    redirectToCheckout({ sessionId: session.id });
  };

  return (
    <div className="checkout-container">
      <h2>Complete Purchase</h2>
      <button onClick={handlePayment} disabled={isLoading}>
        {isLoading ? 'Creating session...' : 'Buy Now ($99.00)'}
      </button>

      {/* Alternative drop-in React Button component */}
      <XRPayButton 
        amount={99.00} 
        currency="USD"
        onSuccess={(session) => console.log('Paid successfully:', session.id)} 
      />
    </div>
  );
}

REST API Reference

Base URL: https://xrpay.it/api/v1. Access requires authenticate headers with API keys.

MethodEndpointAuth ScopeDescription
POST/sessionspk_* or sk_*Create a checkout session
GET/sessions?id=Xpk_* or sk_*Retrieve a session
GET/sessionssk_*List all sessions (paginated)
POST/webhookssk_*Register a webhook endpoint
GET/webhookssk_*List configured webhooks
DELETE/webhooks?id=Xsk_*Delete webhook endpoint
POST/webhooks?id=X&testsk_*Send test webhook ping
GET/balancesk_*Query organization balances
GET/transactionssk_*List completed transactions
GET/payment/:id/statuspublicRetrieve checkout status
GET/x402pk_* or sk_*x402 protocol information
POST/x402/verifysk_*Verify an x402 payment

CURL Creation Sample

bash
curl -X POST https://xrpay.it/api/v1/sessions \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "currency": "USD",
    "customer_email": "customer@example.com",
    "settlement_currency": "RLUSD",
    "metadata": { "invoice_id": "inv_109283" }
  }'