Swipelux
Client-side integration

Supported widget settings

Overview

The Swipelux widget can be customized through various configuration options to match your application's needs. Below is the complete reference of available settings:

export type WidgetSettings = {
  /**
   * Merchant API key in UUID format.
   * @example "123e4567-e89b-12d3-a456-426655440000"
   */
  apiKey: string;
  /**
   * URL where the widget is hosted.
   * @default "https://app.swipelux.com"
   */
  widgetUrl?: string;
  /**
   * Order token, used for prepared orders.
   * @example "ord_123xyz"
   */
  orderToken?: string;
  /**
   * Preferred payment channel.
   * @example "CARD_PAYMENT"
   */
  paymentChannel?: PaymentChannel;
  /**
   * Available payment currency code.
   * @example "USD"
   */
  availablePayCurrency?: string;
  /**
   * Available receive currency configuration.
   * Accepts a string like "BTC", "ETH", etc., or an object with code and protocol.
   * @example "BTC"
   * @example { code: "ETH", protocol: "ERC20" }
   */
  availableReceiveCurrency?: string | CurrencyReference;
  /**
   * Default form values.
   * @example { email: { value: "user@example.com", editable: false } }
   */
  defaultValues?: DefaultValues;
  /**
   * Theme color overrides.
   * @example { main: "#FF0000", background: "#FFFFFF" }
   */
  colors?: Partial<ThemeColors>;
  /**
   * External ID resolver.
   * @example "ext_123"
   * @example async () => await getExternalIdFromServer()
   */
  externalId?: ExternalIdResolver;
  /**
   * Force creation of a new transaction.
   * @example true
   */
  forceNewTransaction?: boolean;
  /**
   * Auto-close the widget on a successful transaction.
   * @example true
   */
  closeOnSuccess?: boolean;
}
 
export type Color =
  | `rgb(${number}, ${number}, ${number})`
  | `rgba(${number}, ${number}, ${number}, ${number})`
  | `hsl(${string})`
  | `#${string}`;
 
export type ThemeColors = {
  main: Color;
  background: Color;
  processing: Color;
  warning: Color;
  success: Color;
  link: Color;
};
 
export type PaymentChannel =
  | "OPEN_BANKING"
  | "CARD_PAYMENT"
  | "WIRE_TRANSFER"
  | "APPLE_PAY";
 
export type DefaultValue = {
  value: string;
  editable: boolean;
};
 
export type DefaultValues = {
  targetAddress?: DefaultValue;
  phone?: DefaultValue;
  email?: DefaultValue;
  fiatAmount?: number;
};
 
export type CurrencyReference = {
  code: string;
  protocol?: string;
};
 
export type ExternalIdResolver = string | (() => Promise<string>);

Example implementation

In this article, all of the example implementations will be based on the client-side integration using the JavaScript SDK.

index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- Your head content here -->
    <script
      crossorigin="anonymous"
      src="https://cdn.jsdelivr.net/npm/@swipelux/onramp-js@^1.0.0"
    ></script>
  </head>
  <body>
    <!-- Your body content here -->
    <div id="swipelux-container"></div>
    <script>
      const widget = new SwipeluxWidget({
        apiKey: "YOUR_PUBLISHABLE_API_KEY",
        // Additional widget settings can be added here...
        // orderToken: "YOUR_ORDER_TOKEN",
      });
      widget.mount(document.getElementById("swipelux-container"));
    </script>
  </body>
</html>

For brevity, the following examples will only show the constructor configuration for SwipeluxWidget. The full implementation remains the same as shown in the basic example above.

Customizing the widget's appearance

Colors

Customize the widget's appearance by modifying color values. All colors are optional and support the following formats:

  • HEX (e.g., #F24F21)
  • RGB (e.g., rgb(213 47 47))
  • HSL (e.g., hsl(0deg 0% 0%))

Supported color keys and their default values

const colors = {
  main: "#000000",        // Primary UI elements
  background: "#FFFFFF",  // Widget background
  processing: "#FFA400",  // Processing state
  warning: "#ED0A34",     // Warning messages
  success: "#58CB4E",     // Success states
  link: "#F24F21",        // Interactive links
};

Example usage

const widget = new SwipeluxWidget({
  apiKey: "YOUR_PUBLISHABLE_API_KEY",
  colors: {
    main: "#000000",
    background: "#FFFFFF",
  },
});

Mapping your orders

Order token

The orderToken parameter is used to initiate the widget with a prepared order created using our REST API.

Example usage

const widget = new SwipeluxWidget({
  apiKey: "YOUR_PUBLISHABLE_API_KEY",
  orderToken: "YOUR_ORDER_TOKEN",
});

External ID

The externalId parameter allows you to link Swipelux orders to your own system's order IDs or references.

Requirements

  • Maximum length: 64 characters

Example usage

// If you know the external ID in advance
const widget = new SwipeluxWidget({
  apiKey: "YOUR_PUBLISHABLE_API_KEY",
  externalId: "YOUR_EXTERNAL_ID",
});
 
// If you don't know the external ID in advance
const widget = new SwipeluxWidget({
  apiKey: "YOUR_PUBLISHABLE_API_KEY",
  externalId: async () => await getExternalIdFromServer(),
});

Specifying payment and receive currencies

Payment currency

Specify the fiat currency that will be used for payment processing. This setting determines which currency your users will pay with when using the widget.

For example, if you set this to USD, users will make payments in US dollars.

Example usage

const widget = new SwipeluxWidget({
  apiKey: "YOUR_PUBLISHABLE_API_KEY",
  availablePayCurrency: "USD",
});

Payment channel

Specify the payment channel that will be used for payment processing. This setting determines which payment method your users will use when using the widget.

For example, if you set this to OPEN_BANKING, users will skip the payment method selection step and initiate the payment process using Open Banking immediately after confirming the order.

Supported payment channels

  • OPEN_BANKING - Use the Open Banking payment method.
  • CARD_PAYMENT - Use the card payment method.
  • WIRE_TRANSFER - Use the bank wire transfer payment method.
  • APPLE_PAY - Use the Apple Pay payment method. This payment method is only available for users with an Apple Pay-enabled device. If it's not available, the user will be forced to select another payment method.

Example usage

const widget = new SwipeluxWidget({
  apiKey: "YOUR_PUBLISHABLE_API_KEY",
  paymentChannel: "OPEN_BANKING",
});

Receive currency

Specify the cryptocurrency that you want to receive when users make a purchase through the widget. This can be configured either as a simple currency code or with additional protocol specifications for tokens.

Example usage

// Simple configuration
const widget = new SwipeluxWidget({
  apiKey: "YOUR_PUBLISHABLE_API_KEY",
  availableReceiveCurrency: "ETH"
});
 
// With protocol specification
const widget = new SwipeluxWidget({
  apiKey: "YOUR_PUBLISHABLE_API_KEY",
  availableReceiveCurrency: {
    code: "USDC",
    protocol: "MATIC"
  }
});

Pre-filling user information

You can pre-fill user information and order amounts using the defaultValues property to enhance the user experience.

For each field (except fiatAmount), you can specify whether it should be editable or locked, giving you control over which information users can modify.

Example usage

const defaultValues = {
  phone: {
    value: "19998885522",
    editable: false,
  },
  email: {
    value: "user@example.com",
    editable: true,
  },
  fiatAmount: 200,
};
 
const widget = new SwipeluxWidget({
  apiKey: "YOUR_PUBLISHABLE_API_KEY",
  defaultValues: defaultValues,
});

Integrating on mobile

Previous Page

Create an order

Next Page

On this page