React checkout widget

@payitgo/react shows a payment on your own page, in a modal: the customer chooses the coin, sees the exact amount, network, QR code, address (and XRP destination tag), pays from their wallet, and watches the payment confirm. It needs no key. Your server creates the payment and hands the browser its checkout_token; the widget calls the public checkout API and follows the payment live.

Show a payment

In the browser, a button that opens the checkout:

import { PayitgoButton, payitgoCheckout } from "@payitgo/react";

const adapter = payitgoCheckout({
  baseUrl: "https://api.payitgo.co",
  // Ask your server for the payment and return its checkout_token.
  createPayment: async () =>
    (await fetch("/orders/42/payitgo", { method: "POST" }).then((r) => r.json())).checkout_token,
});

export function PayButton() {
  return (
    <PayitgoButton
      adapter={adapter}
      payment={{ title: "Order #42", amount: { value: 49.9, currency: "USD" } }}
      onSuccess={(result) => showThanks(result.paymentId)}
    >
      Pay with crypto
    </PayitgoButton>
  );
}

On your server, the route the widget calls creates the payment with your secret key (Node.js library here; any library, or POST /v1/payments, does the same) and answers with its checkout_token:

import { Payitgo } from "@payitgo/node";

const payitgo = new Payitgo(process.env.PAYITGO_KEY!, { baseUrl: "https://api.payitgo.co" });

app.post("/orders/:id/payitgo", async (req, res) => {
  const order = await orders.get(req.params.id);
  // No token: the customer chooses the coin in the widget.
  const payment = await payitgo.payments.create({ order_id: order.id, amount_usd: order.total });
  res.json({ checkout_token: payment.checkout_token });
});

Never put a secret key in browser code. The checkout token only shows the payer's view of one payment.

Each time the widget opens it calls createPayment() again. While the order has an open payment, creating it again returns that same payment (safe retries), so a customer who closes and reopens the widget sees the same address and amount.

onSuccess runs in the customer's browser and is not proof of payment. Fulfil orders from the payment.confirmed webhook.

Without a server: a payment link

A payment link needs no key to pay, so a page without a server of its own can start its payment from the browser with POST /links/{id}/checkout:

const adapter = payitgoCheckout({
  baseUrl: "https://api.payitgo.co",
  createPayment: async () => {
    const r = await fetch(`https://api.payitgo.co/links/${linkId}/checkout`, { method: "POST" });
    const body = await r.json();
    if (!r.ok) throw new Error(body.error); // "this payment link can no longer be paid"…
    return body.checkout_token;
  },
});

Next.js

Render the widget from a client component: the adapter and onSuccess are functions, which a server component cannot pass down. Nothing renders on the server; the modal opens in the browser.

The adapter

payitgoCheckout(options: PayitgoCheckoutOptions): PayitgoAdapter

Connects the widget to payitgo.

What it calls, all from the browser, with no credentials:

All of them answer any origin, so no proxy is needed. A POST answered 429 is sent again once, a second later. If you put a proxy in front of the gateway anyway (baseUrl: "https://shop.example/payitgo"), it must forward WebSocket upgrades on /payitgo/socket.io/: a plain HTTP rewrite cannot carry the WebSocket (the widget then polls instead).

PayitgoError

What the adapter throws: the API's message (capitalised) and HTTP status.

The widget shows them itself, with a way to try again; you only meet them in a custom adapter or around your own calls.

Components

PayitgoButton

A button that opens the checkout. It takes every PayitgoCheckout prop except open, plus:

PayitgoCheckout

The modal itself, controlled: render it anywhere, it portals to document.body while open. Every opening starts with createPayment().

What the customer sees

Every transfer in deposits[] is listed with its confirmations, marked "Not counted" (another coin) or "Late". A payment priced in your currency shows that price next to the dollars. An unknown checkout token shows "Payment not found", with no retry and no new payment.

Test payments

A test payment shows a "Test payment" banner and buttons that play what the customer does, through the real processing: deposits, status changes and your webhooks (Test mode). Live payments never show them.

Custom adapters

PayitgoAdapter is an interface: start(payment) returns a checkout token, get(checkoutToken) and chooseToken(checkoutToken, token) return the payment as GET /checkout/{token} does. Two optional methods turn on more: subscribe(checkoutToken, { onPayment, onConnection, onNotFound }) follows the payment live (it returns the function that stops), and simulate(checkoutToken, outcome) shows the simulate buttons on test payments. Without subscribe, the widget polls get() every pollIntervalMs.

demoAdapter simulates everything offline, with addresses no wallet accepts: for previews and design work.

Content Security Policy

The widget adds one <style> element to the page the first time it opens, and styles some elements inline: a style-src must allow 'unsafe-inline'. connect-src must allow the gateway, over https: and wss:.