Bitrefill Widget

Playground

Try the widget like your users will. Tweak settings, see live events, copy production-ready code.

# Referral Token

You can set the referral token by passing the ref query parameter. To see your referral token, login to your Bitrefill account and return to this page.

Example

const referralToken = YOUR_REFERRAL_TOKEN;

const embedUrl = `https://embed.bitrefill.com/?ref=${referralToken}`;

console.log(embedUrl);
// -> https://embed.bitrefill.com/?ref=YOUR_REFERRAL_TOKEN

You can set the payment methods that are available to the user by passing the paymentMethods query parameter. The value should be a comma separated list. The available payment methods are: bitcoin, dash, dogecoin, eth_base, ethereum, lifi, lightning, litecoin, solana, ton, usdc_arbitrum, usdc_base, usdc_erc20, usdc_polygon, usdc_solana, usdt_arbitrum, usdt_bsc, usdt_erc20, usdt_polygon, usdt_ton, usdt_trc20

Example

const paymentMethods = [
  "bitcoin",
  "dash",
  "dogecoin",
  "eth_base",
  "ethereum",
  "lifi",
  "lightning",
  "litecoin",
  "solana",
  "ton",
  "usdc_arbitrum",
  "usdc_base",
  "usdc_erc20",
  "usdc_polygon",
  "usdc_solana",
  "usdt_arbitrum",
  "usdt_bsc",
  "usdt_erc20",
  "usdt_polygon",
  "usdt_ton",
  "usdt_trc20",
].join(",");

const embedUrl = `https://embed.bitrefill.com/?paymentMethods=${paymentMethods}`;

console.log(embedUrl);
// -> https://embed.bitrefill.com/?paymentMethods=bitcoin,dash,dogecoin,eth_base,ethereum,lifi,lightning,litecoin,solana,ton,usdc_arbitrum,usdc_base,usdc_erc20,usdc_polygon,usdc_solana,usdt_arbitrum,usdt_bsc,usdt_erc20,usdt_polygon,usdt_ton,usdt_trc20

# Theme

You can set the theme by passing the theme query parameter. The available themes are: auto, light, dark. The default theme is auto. For more customization options see the Custom Styles query parameter.

Example

const themes = [
  'auto',
  'light',
  'dark',
];

const theme = themes[2];

const embedUrl = `https://embed.bitrefill.com/?theme=${theme}`;

console.log(embedUrl);
// -> https://embed.bitrefill.com/?theme=dark

# Language

You can set the language by passing the hl query parameter. The available languages are: en, ru, fr, es, de, it, nl, pt, vi, ko, ja, zh-Hans, pl, uk, tr. The default language is determined by the user's browser.

Example

const languages = [
  'en', // English
  'ru', // Russian
  'fr', // French
  'es', // Spanish
  'de', // German
  'it', // Italian
  'nl', // Dutch
  'pt', // Portuguese
  'vi', // Vietnamese
  'ko', // Korean
  'ja', // Japanese
  'zh-Hans', // Chinese Simplified
  'pl', // Polish
  'uk', // Ukrainian
  'tr', // Turkish
];

const language = languages[0];

const embedUrl = `https://embed.bitrefill.com/?hl=${language}`;

console.log(embedUrl);
// -> https://embed.bitrefill.com/?hl=en

# Company Name

You can set the company name by passing the utm_source query parameter. The purpose of this parameter is for analytics.

Example

const utmSource = 'bitrefill'; // your company or wallet name

const embedUrl = `https://embed.bitrefill.com/?utm_source=${utmSource}`;

console.log(embedUrl);
// -> https://embed.bitrefill.com/?utm_source=bitrefill

# Email

You can set the user's email address by passing the email query parameter. This allows us to skip the email step in the checkout.

Example

const email = getUserEmail(); // your code to get the user's email

const embedUrl = `https://embed.bitrefill.com/?email=${email}`;

console.log(embedUrl);
// -> https://embed.bitrefill.com/?email=example%40example.com

# Refund Address

You can set the user's refund address by passing the refundAddress query parameter.

Example

const refundAddress = getUserRefundAddress(); // your code to get the user's refund address

const embedUrl = `https://embed.bitrefill.com/?refundAddress=${refundAddress}`;

console.log(embedUrl);
// -> https://embed.bitrefill.com/?refundAddress=bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq

# Show Payment Info

You can set whether or not to show the payment info by passing the showPaymentInfo query parameter. The default value is true. When you set this to false the user will not see the payment info step in the checkout, make sure you check out and implement the payment_intent event. See the section for more information.

Example

const showPaymentInfo = false;

const embedUrl = `https://embed.bitrefill.com/?showPaymentInfo=${showPaymentInfo}`;

console.log(embedUrl);
// -> https://embed.bitrefill.com/?showPaymentInfo=false

# Pending Payment

If you are using the paymentIntent event and redirect the user to their wallet to pay we have a ?paymentPending=true param which is sometimes necessary if the browser session closes when the user leaves to pay the transaction in their wallet.

# Custom Styles

The Bitrefill Widget provides a flexible way to customize the appearance of your embeds through a feature called customStyles. This feature allows you to pass CSS variables and their corresponding values to the embed as a URL parameter.

We recommend editing the semantic variables below. For deeper control, you can also override the base color primitives (e.g. --gray-100, --deep-green-300) that these reference.

To employ customStyles, you are required to pass an object where the key corresponds to the CSS variable and the value represents the CSS value. This object needs to be converted into a string using JSON.stringify(), and subsequently, the resulting string should be processed through encodeURIComponent() to guarantee its safe inclusion within the URL.

The customStyles parameter should be appended to the embed URL as follows:

Example

const customStyles = {
  "--white": "#fff",
  // See below for a full list of valid and editable css variables
};

const embedUrl =
  `https://embed.bitrefill.com?customStyles=${
      encodeURIComponent(
        JSON.stringify(customStyles)
      )
  }`;

Default Styles

:root {
  /* Foundation */
  --brand: var(--rich-orange-300);
  --brand-background: var(--brand);
  --brand-text: var(--white);
  --brand-secondary-background: var(--deep-green-300);
  --brand-secondary-text: var(--white);
  --brand-yellow: hsl(45deg 100% 48%);

  /* Background */
  --background-body: var(--white);
  --background-primary: var(--white);
  --background-secondary: var(--gray-100);
  --background-contrast: var(--gray-300);
  --background-opaque: rgb(255 255 255 / 70%);
  --background-region: var(--gray-300);
  --background-yellow: var(--yellow-200);

  /* Text */
  --text-primary: var(--deep-green-300);
  --text-secondary: var(--gray-600);
  --text-tertiary: var(--gray-500);
  --text-accent: var(--red-500);
  --text-link: var(--deep-green-400);
  --text-inverted: var(--white);

  /* Border */
  --border-primary-color: var(--gray-300);
  --border-secondary-color: var(--gray-300);
  --border-divider-color: var(--gray-200);
  --border-overlay-color: hsl(0deg 0% 0% / 7%);
  --border-primary: 1px solid var(--border-primary-color);
  --border-secondary: 1px solid var(--border-secondary-color);
  --border-divider: 2px solid var(--border-divider-color);
  --border-overlay: 1px solid var(--border-overlay-color);

  /* Emotion */
  --neutral: var(--text-primary);
  --warning: var(--yellow-500);
  --positive: var(--green-500);
  --negative: var(--red-400);

  /* Interactive */
  --interactive-primary: var(--deep-green-300);
  --interactive-primary-hover: var(--deep-green-400);
  --interactive-primary-active: var(--deep-green-500);
  --interactive-secondary: var(--gray-300);
  --interactive-secondary-hover: var(--gray-400);
  --interactive-secondary-active: var(--gray-500);
  --interactive-tertiary: var(--gray-200);
  --interactive-tertiary-hover: var(--gray-300);
  --interactive-tertiary-active: var(--gray-400);
  --interactive-accent: var(--rich-orange-300);
  --interactive-accent-hover: var(--rich-orange-400);
  --interactive-accent-active: var(--rich-orange-500);

  /* Various */
  --shadow-0: none;
  --shadow-1: 0 1px 3px rgb(0 0 0 / 6%), 0 1px 2px rgb(0 0 0 / 10%);
  --shadow-2: 0 3px 6px rgb(0 0 0 / 15%), 0 2px 4px rgb(0 0 0 / 12%);
  --shadow-insert: inset 0 1px 1px rgb(0 0 0 / 10%), inset 0 1px 4px rgb(0 0 0 / 6%);

  --backdrop: rgb(0 0 0 / 20%);
  --focus-ring-color: var(--deep-green-300);

  --preheader-bg: var(--gray-900);
  --preheader-color: var(--white);

  --tooltip-bg: var(--gray-900);
  --tooltip-color: white;
  --cashback-color: var(--yellow-500);
}

Code Samples

Copy and paste into your project.

<!-- This was code was generated with https://bitrefill.com/playground -->
<iframe
  width="375"
  height="667"
  src="https://embed.bitrefill.com/?showPaymentInfo=false&utm_source=bitrefill_demo&theme=light"
  sandbox="allow-same-origin allow-popups allow-scripts allow-forms"
/>
<script>
  window.onmessage = function(e) {
    if (e.origin !== 'https://embed.bitrefill.com') {
      return;
    }

    const {
      event,
      invoiceId,
      paymentUri
    } = e.data;

    switch(event) {
      case 'payment_intent':
        // Pay the users invoice with the `paymentUri`
        break;
      default:
        break;
    }

  }
</script>

Bitrefill Widget

Playground

Live Events

# Referral Token

# Payment Methods

# Theme

# Language

# Company Name

# Email

# Refund Address

# Show Payment Info

# Pending Payment

# Custom Styles

Code Samples

Live on crypto

Support

Company

Resources