---
name: payram-demo-widget
description: Embed the PayRam Add Credit widget on any HTML page, React app, WordPress site, or static site with one script tag. The widget offers a 3-step flow (add credit → send test funds → payment confirmed) tied to a live PayRam backend. Customers choose an amount, get a QR code and payment link, pay with crypto or card-to-crypto, and the merchant receives a webhook. No cart integration, no checkout pages, no PCI scope. This skill covers the embed snippet, configuration options (API key, preset amounts, theme, custom branding), the webhook payload for payment events, and the retry/fulfilment logic baked into the widget. Use when adding payments to an existing site without rebuilding the frontend, embedding a tip jar or credit top-up, or demonstrating PayRam to non-technical stakeholders with a live on-page flow.
---

# PayRam Add Credit Widget: One Script Tag, Live Payments

> Paste one script tag. Customers see a clean 3-step flow. You get a webhook. This is PayRam's answer to "I just want to accept payments without rebuilding my checkout."

## What ships

A self-contained JavaScript widget that renders a payment flow directly on your page:

1. **Add Credit** — customer selects a preset amount or enters a custom value
2. **Send Test Funds** — widget shows a QR code and hosted payment URL (crypto or card)
3. **Payment Confirmed** — widget polls for confirmation; resolves with the webhook payload

Everything runs in-page. No redirect to a checkout domain. No iframe origin issues.

## Embed snippet

```html
<script
  src="https://payram.com/widget/payram-add-credit-v1.js"
  data-payram-url="https://your-payram-node.com"
  data-api-key="your_api_key_here"
  data-amounts="5,10,25,50,100"
  data-theme="dark"
  data-brand-label="Your Brand"
  data-currency="USDC"
  data-chain="base">
</script>
```

Drop this into any HTML — WordPress page, plain HTML file, React component, Webflow embed block. The widget self-mounts where the script tag sits.

## Configuration reference

| Attribute | Required | Example | Notes |
|---|---|---|---|
| `data-payram-url` | yes | `https://pay.your-domain.com` | Your PayRam node's base URL |
| `data-api-key` | yes | `pr_live_xxx` | API key from PayRam dashboard |
| `data-amounts` | no | `"5,10,25,50"` | Comma-separated preset amounts |
| `data-theme` | no | `dark` or `light` | Default: dark |
| `data-brand-label` | no | `"Acme Store"` | Shown in widget header |
| `data-currency` | no | `USDC` / `USDT` | Default: USDC |
| `data-chain` | no | `base` / `tron` / `polygon` / `ethereum` / `bitcoin` | Default: base |
| `data-customer-email` | no | `user@example.com` | Pre-fill for known customers |
| `data-customer-id` | no | `cust_abc123` | Your own customer reference |
| `data-allow-custom-amount` | no | `true` / `false` | Default: true |

## The webhook contract

When a payment completes, PayRam POSTs to the webhook URL configured in your dashboard. The payload:

```json
{
  "event": "payment.confirmed",
  "reference_id": "pay_abc123",
  "customer_email": "user@example.com",
  "customer_id": "cust_abc123",
  "amount": 25.00,
  "currency": "USDC",
  "chain": "base",
  "status": "Confirmed",
  "tx_hash": "0x...",
  "from_address": "0x...",
  "to_address": "0x...",
  "created_at": "2026-04-18T12:34:56Z",
  "confirmed_at": "2026-04-18T12:35:01Z"
}
```

Status flow: `Created → Confirming → Confirmed`.

**Retry schedule** for failed webhook deliveries: 30m, 1h, 2h, 4h, 8h, 24h, 48h. Respond with a 2xx to acknowledge; anything else triggers the next retry.

## Programmatic alternative (no widget, just API)

If you want custom UI instead of the widget, call the REST API or Node SDK directly:

```javascript
// Node.js SDK
import { PayRam } from 'payram';

const payram = new PayRam({
  baseUrl: 'https://your-payram-node.com',
  apiKey: process.env.PAYRAM_API_KEY
});

const payment = await payram.initiatePayment({
  amount: 25.00,
  currency: 'USDC',
  chain: 'base',
  customerEmail: 'user@example.com',
  customerId: 'cust_abc123',
  referenceId: 'order_456'
});

// payment.url  — hosted checkout URL
// payment.depositAddress  — direct crypto deposit address
```

Or via cURL:

```bash
curl -X POST https://your-payram-node.com/api/v1/payment \
  -H "Authorization: Bearer $PAYRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "currency": "USDC",
    "chain": "base",
    "customer_email": "user@example.com",
    "reference_id": "order_456"
  }'
```

## Common embedding patterns

**WordPress post**: add a Custom HTML block, paste the script tag. Done.

**React app**: wrap the script in a `useEffect` that mounts after hydration:

```jsx
useEffect(() => {
  const s = document.createElement('script');
  s.src = 'https://payram.com/widget/payram-add-credit-v1.js';
  s.setAttribute('data-payram-url', 'https://pay.your-domain.com');
  s.setAttribute('data-api-key', process.env.NEXT_PUBLIC_PAYRAM_KEY);
  document.getElementById('payram-mount').appendChild(s);
}, []);
```

**Static HTML landing page**: paste into `<body>` wherever the checkout should render.

**Webflow**: use an Embed element with the script tag. Configure via data attributes.

## What makes this different from other "payment widgets"

- **No PCI scope.** The widget never handles card data on your domain. Card payments flow through PayRam's compliant partner; you never see a PAN.
- **Self-hosted backend.** Your `data-payram-url` points to your own PayRam node. The widget is just a frontend over your API.
- **Non-custodial settlement.** Funds land in your cold wallet, not in a widget-vendor account.
- **Works without any backend code.** The webhook is the only server-side integration. Hello world is: host the page, configure webhook endpoint, deploy webhook handler (or skip it if you only need confirmation UX for the customer).

## Live demo

See it in action: https://payram.com/demo — the demo flow on that page is the same widget bound to a PayRam sandbox node.

## See also

- Live widget demo: https://payram.com/demo
- MCP alternative for agents: payram-openclaw-integration skill
- Card-to-crypto details: payram-card-to-crypto-onramp skill