Payment

For installation instructions, see Getting Started with Unify Widgets.

Basic Implementation

<unify-payment-widget
  api-key="your-api-key"
  location-id="your-location-id"
></unify-payment-widget>

const widget = document.querySelector('unify-payment-widget');

// Set the order object (format defined by the Unify API)
widget.order = { /* order data */ };

widget.addEventListener('payment-success', (event) => {
  console.log('Payment complete via:', event.detail.method);
});

Component Attributes

Attribute	Type	Required	Description
`api-key`	String	Yes	API key for Unify requests
`location-id`	String	Yes	Store location ID where payment is processed
`demo`	Boolean	No	Enable demo mode for testing

Component Properties

Property	Type	Required	Description
`config`	Object	No	Configuration object (see Config Options)
`order`	Object	Yes	Order data to process. Format is defined by the Unify API — set this before calling `selectPaymentMethod()`

Read-only state

These properties are reflected as HTML attributes and can be observed via JS or used in CSS selectors:

Property / Attribute	Values	Description
`paymentMethod`	`''`, `'cash-register'`, `'qrcode'`	Currently active payment method
`paymentState`	`'idle'`, `'sending'`, `'success'`, `'error'`	Current payment processing state

/* Example: style the widget based on state */
unify-payment-widget[payment-state="success"] { ... }

Methods

`selectPaymentMethod(method)`

Programmatically select and process a payment method.

widget.order = { /* order data */ };
await widget.selectPaymentMethod('cash-register');

Parameters:

method (String): 'cash-register' or 'qrcode'

Returns: Promise — resolves when processing completes, rejects on error.

`resetPayment()`

Reset the widget to its initial (idle) state.

widget.resetPayment();

Config Options

document.querySelector('unify-payment-widget').config = {
  enabledPaymentMethods: ['cash-register', 'qrcode'],
  cashRegisterPaymentMethodName: 'Pay at Store',
};

Payment Methods & Labels

Option	Default	Description
`enabledPaymentMethods`	`['cash-register', 'qrcode']`	Array of enabled payment methods
`cashRegisterPaymentMethodName`	`"Pay at Cash Register"`	Label for cash register option
`qrcodePaymentMethodName`	`"Pay with QR Code"`	Label for QR code option
`payAtCashRegisterSuccessText`	`"Proceed to pay at your cash register."`	Text shown after cash register selection

Error Handling

Option	Default	Description
`defaultErrorMessage`	`"An error occurred during payment processing."`	Fallback error message
`showErrorDetails`	`false`	Show detailed error information when available

Styling

CSS Custom Properties (recommended)

unify-payment-widget {
  --unify-payment-method-border: #333;
  --unify-payment-method-bg: white;
  --unify-payment-method-color: black;
  --unify-payment-method-option-width: 117px;
  --unify-payment-method-option-height: 100px;
  --unify-pay-button-min-height: 400px;
  --unify-pay-button-border: black;
  --unify-pay-button-bg: transparent;
  --unify-pay-button-color: black;
}

To discover all available properties, inspect the widget element in browser DevTools and look at the Computed tab for all --unify-* entries.

CSS Parts

unify-payment-widget::part(payment-method-selector-option) {
  border-radius: 8px;
}

⚠️ Parts may change between versions. Use CSS custom properties where possible.

Events

`payment-success`

Fired when payment is successfully processed.

widget.addEventListener('payment-success', (event) => {
  console.log('Method used:', event.detail.method);
});

Detail shape:

{
  method: string  // 'cash-register' or 'qrcode'
}

`payment-error`

Fired when payment processing encounters an error.

widget.addEventListener('payment-error', (event) => {
  console.error('Payment failed:', event.detail.error);
});

Detail shape:

{
  error: string,   // Error message
  method: string   // 'cash-register' or 'qrcode'
}

Example

const widget = document.querySelector('unify-payment-widget');

widget.config = {
  enabledPaymentMethods: ['cash-register', 'qrcode'],
  cashRegisterPaymentMethodName: 'Pay at Register',
  qrcodePaymentMethodName: 'Scan to Pay',
};

widget.order = { /* order object from your Unify integration */ };

widget.addEventListener('payment-success', (event) => {
  console.log(`Payment completed via ${event.detail.method}`);
});

widget.addEventListener('payment-error', (event) => {
  console.error(`Payment failed: ${event.detail.error}`);
  widget.resetPayment();
});