ATOM Sales Widget Installer Docs

This package is designed to be installable on any domain that can serve static files and run PHP. The front end works anywhere; the full verification + webhook flow requires PHP for /sales/api/verify-sale.php.

1. Upload paths

Upload the contents of the sales folder directly into your website's /sales/ directory.

/public_html/sales/
  index.html
  widget.js
  widget.html
  docs.html
  api/
  storage/
  README.md

That should produce these public URLs:

• /sales/ → builder page
• /sales/widget.js → embeddable script
• /sales/widget.html → iframe-ready widget
• /sales/docs.html → docs
• /sales/api/verify-sale.php → backend verification endpoint

2. Backend setup

1. Copy /sales/api/config.example.php to /sales/api/config.php.
2. Update downstream_webhook_url and downstream_webhook_secret.
3. Make sure /sales/storage/ is writable by PHP.

On many cPanel hosts, that means 755 for folders and ensuring PHP can write to the storage directory. If needed, use 775 on /sales/storage/.

3. Front-end builder portability

The builder now includes a Widget install base URL field. Set it to your own domain path, for example:

https://yourdomain.com/sales

Generated script and iframe embeds will then point to your own domain instead of atomregistry.com.

4. Script embed example

<div id="atom-sales-widget"></div>
<script src="https://yourdomain.com/sales/widget.js"></script>
<script>
  window.AtomSalesWidget.mount('#atom-sales-widget', {
    title: 'Pay with ATOM',
    walletAddress: 'cosmos1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    amountAtom: '5',
    itemName: 'Premium Access',
    memo: 'Order: Premium Access',
    successUrl: 'https://yourdomain.com/thank-you',
    verifyEndpoint: 'https://yourdomain.com/sales/api/verify-sale.php',
    enableKeplr: true,
    allowManualFallback: true,
    addressVisibility: 'checkout',
    showMintscan: true
  });
</script>

5. Verification payload

After a successful in-widget transaction, the widget can POST this payload to your verification endpoint:

{
  "txhash": "...",
  "sender_address": "cosmos1...",
  "recipient_address": "cosmos1...",
  "amount_atom": "5",
  "amount_uatom": "5000000",
  "memo": "Order: Premium Access",
  "item_name": "Premium Access",
  "chain_id": "cosmoshub-4"
}

6. What verify-sale.php does

• fetches the tx from Cosmos Hub LCD endpoints
• checks that the tx succeeded
• checks recipient match
• checks amount match
• checks memo match when provided
• checks denom is uatom
• stores processed tx hashes to block duplicate fulfillment
• optionally fires your downstream webhook

7. How to test it

1. Open /sales/ on your installed domain.
2. Set your real install base URL in the builder.
3. Set your real verify endpoint to your domain's /sales/api/verify-sale.php.
4. Generate a test widget.
5. Run a small ATOM test payment from Keplr.
6. Confirm the widget shows a Mintscan link.
7. Check /sales/storage/verify-sale.log for verification activity.
8. Confirm your downstream webhook endpoint received a verified payload.

8. Domain compatibility

Yes, this can be installed on any domain as long as that domain/server can:

• serve static files
• run PHP
• allow outbound HTTPS requests to Cosmos Hub LCD endpoints and your webhook target

If you deploy on a static-only host with no PHP, the widget UI can still work, but the verification endpoint and webhook automation will not.

9. Production checklist

• Do not trust the client callback alone. Always verify tx hash on the backend before fulfillment.
• Use a memo scheme your order system can match cleanly.
• Use address visibility checkout or hidden if you do not want the wallet displayed publicly.
• Keep your verify endpoint same-origin or CORS-enabled for the domains that host the widget.
• Test duplicate tx behavior before going live.