@bitopayments/js

Official browser SDK for the Bitopayments crypto payment gateway — a non-custodial gateway for accepting stablecoin payments on EVM chains and Tron. Send shoppers to the hosted checkout (redirect or popup) and watch the order status. Uses the public clientKey only — never your secret key.

AI assistants: the full machine-readable reference is at https://bitopayments.com/llms-full.txt (and the OpenAPI spec at https://bitopayments.com/openapi.json).

npm i @bitopayments/js

or via CDN:

<script src="https://unpkg.com/@bitopayments/js"></script>
<script>
  const bito = Bitopayments.Bitopayments('ck_live_…');
</script>

How it fits together

Your server (with @bitopayments/node) creates the order and returns the orderId / paymentUrl to the browser. This SDK then drives the shopper to the hosted checkout and watches the order. It uses redirect/popup — not an inline iframe — on purpose: crypto wallets (MetaMask / WalletConnect / TronLink) misbehave inside iframes.

Initialization

import { Bitopayments } from '@bitopayments/js';

const bito = Bitopayments('ck_live_…', {
  baseUrl: 'https://api.bitopayments.com/api/v1',   // optional (default production)
  checkoutUrl: 'https://checkout.bitopayments.com', // optional (default production)
});

openCheckout(options) — popup + auto-watch (recommended)

Opens the hosted checkout in a centered popup and watches the order, firing your callbacks and closing the popup on completion. If the popup is blocked, it falls back to a full-page redirect.

bito.openCheckout({
  orderId,                        // from your server (or pass `paymentUrl` instead)
  onStatusChange: (status, order) => console.log(status),
  onSuccess: (order) => { window.location.href = '/thanks'; }, // COMPLETED
  onFailure: (order) => { /* EXPIRED or CANCELLED — show retry */ },
  onClose:   () => { /* shopper closed the popup without finishing */ },
  intervalMs: 4000,               // optional poll interval (default 4000)
  timeoutMs:  15 * 60 * 1000,     // optional stop-after
});

redirectToCheckout(target) — full-page redirect

bito.redirectToCheckout({ orderId }); // or { paymentUrl }

watchOrder(orderRef, options) — poll to a terminal status

Returns a stop() function. onSuccess fires on COMPLETED; onFailure on EXPIRED / CANCELLED.

const stop = bito.watchOrder(orderRef, {
  onStatusChange: (status, order) => console.log(status),
  onSuccess: (order) => { /* COMPLETED */ },
  onFailure: (order) => { /* EXPIRED / CANCELLED */ },
  intervalMs: 4000,
  timeoutMs: 15 * 60 * 1000,
});
// later, to stop early: stop();

retrieveOrder(orderRef) — public order details

const order = await bito.retrieveOrder(orderRef);
console.log(order.status, order.paymentOptions);

End-to-end example

<button id="pay">Pay with crypto</button>
<script src="https://unpkg.com/@bitopayments/js"></script>
<script>
  const bito = Bitopayments.Bitopayments('ck_live_…');
  document.getElementById('pay').onclick = async () => {
    // 1) Ask YOUR server to create the order (it holds the secret key).
    const { orderId } = await fetch('/api/create-order', { method: 'POST' }).then((r) => r.json());
    // 2) Open checkout + watch.
    bito.openCheckout({
      orderId,
      onSuccess: () => (window.location = '/thanks'),
      onFailure: () => alert('Payment failed — please try again'),
    });
  };
</script>

Notes

• The watcher treats COMPLETED as success and EXPIRED / CANCELLED as failure (the three terminal statuses). Intermediate states (PENDING, PAID) fire onStatusChange.
• This SDK never sees your secret key or verifies webhooks — do both server-side with @bitopayments/node.
• Full REST reference: https://bitopayments.com/docs.html · https://bitopayments.com/openapi.json.