Developer documentation

Embed the payment widget

Last updated:

The payment widget is a drop-in JavaScript snippet that opens the UnitPay payment form as a pop-up over your site. The customer pays without leaving your page; you receive the result the same way as for any other UnitPay flow — via the signed callback handler. Use it when you want a lighter-touch checkout than a redirect to a hosted page but still don't want to handle card data yourself.

When to use the widget

NeedRecommended option
One-click checkout from a product page or cart, without leaving the sitePayment widget
Server-controlled order amount, custom validation, fraud rulesinitPayment API
Share a hosted URL by email, WhatsApp, or QR codePayment links
Embed checkout in a mobile webviewPayment widget or hosted link — both render the same form

Quick start

Load the widget script and initialise a payment object inside an event handler. Compute the signature on your server — never expose the project secret key to the browser.

<script src="https://widget.unitpay.net/unitpay.js" defer></script>
<button type="button" data-action="pay">Pay IDR 150,000</button>
document.addEventListener('click', function (event) {
  if (event.target.dataset.action !== 'pay') return;

  var payment = new UnitPay();

  payment.createWidget({
    publicKey: '123456-a875a',
    sum: 150000.00,
    account: 'invoice-2026-0184',
    currency: 'IDR',
    desc: 'Invoice #2026-0184',
    locale: 'en',
    signature: '<sha256-hex-digest from your server>'
  });

  payment.success(function (params) {
    // Customer completed the payment in the widget.
    // The authoritative confirmation still arrives via your callback handler.
    window.location.href = '/orders/' + params.account + '/thanks';
  });

  payment.error(function (message, params) {
    console.warn('Widget error:', message, params);
  });
});

Required parameters

ParameterTypeDescription
publicKeystringProject public key. Visible in the merchant cabinet under Settings → Project → Payment widget. Safe to ship in client-side code.
sumnumberPayment amount in major currency units. Two decimal places maximum (for example, 150000.00 for IDR 150,000 or 10.00 for USD 10).
accountstringCustomer or order identifier in your system. Returned unchanged in callbacks so you can reconcile the payment to the original order.
descstringHuman-readable order description shown to the customer on the form and on the receipt.
signaturestringSHA-256 hex digest computed on your server. See Signing the request below.

Optional parameters

ParameterTypeDescription
currencystringISO 4217 currency code: IDR, USD, or EUR. Defaults to the project's primary currency.
localestringWidget language: en or id. Auto-detected from the browser's navigator.language when omitted.
paymentTypestringPre-select a payment method: card, qris, va, or another method enabled on your project. Skip to let the customer choose on the form.
hideMenubooleanWhen true and a paymentType is set, hides the method-selection menu so the customer can only pay with that method.
customerEmailstringCustomer email used for the receipt. Pre-fills the email field on the form.

Signing the request

The widget signature uses a fixed-order recipe (different from the alphabetical sort used by initPayment). Concatenate values separated by the literal four-character delimiter {up}, then take the lowercase SHA-256 hex digest:

signature = sha256_hex(
  account + "{up}" +
  currency + "{up}" +
  desc + "{up}" +
  sum + "{up}" +
  secretKey
)

Notes on the recipe:

  • If you don't pass currency, omit it from the signature too — do not insert an empty string for it.
  • sum is serialised exactly as you pass it to createWidget: 150000.00, not "150000" or 150000.0. A formatting mismatch is the most common cause of "invalid signature" errors.
  • Compute the digest on your server. Send only the digest plus the public-safe parameters to the browser.
  • Rotate the secret key from Settings → Project → Secret key if you suspect compromise. Never commit it to client-side code or version control.

Handling success and error events

payment.success(callback) fires when the customer completes the payment inside the widget. The params object includes the account and sum you supplied; treat it as a UI hint only — the authoritative confirmation arrives on your server via the signed callback handler.

payment.error(callback) fires when the widget cannot process the payment (invalid signature, declined card, customer cancellation). The first argument is a human-readable message; the second carries the parameters that triggered the error.

Don't credit the order, ship the goods, or unlock the digital product on the success event alone. Treat the widget result as a hint, then wait for your callback handler to receive the signed PAY request before fulfilling.

After a successful payment

The widget triggers the same callback flow as every other UnitPay payment method: a signed CHECK request followed by a signed PAY request, both verifiable using your project secret key. See Callback handler. The account field in the callback echoes the value you set on createWidget, so you can match the result to the originating order.

Limitations

  • The widget script must be loaded from https://widget.unitpay.net/unitpay.js. Self-hosting or proxying the script is not supported — new releases ship via that URL.
  • Your site's Content Security Policy must allow script-src https://widget.unitpay.net and frame-src https://pay.unitpay.net.
  • The widget renders inside an iframe. It cannot be embedded in pages served over plain HTTP — HTTPS is required.
  • One UnitPay instance handles one payment at a time. To support multiple "Pay" buttons on a page, create a fresh instance per click.
  • Some mobile in-app browsers (older Facebook / Instagram webviews) block third-party iframes; for those audiences, fall back to a hosted payment link.

Next steps