Skip to main content

Web3 Tip Widget

Self-host and controll the entire tip flow within your app.

Example​

Tip

Amount

$10.00

Payment

ETH0.0024

Installation​

Package​

You can install DePay Widgets via yarn or npm and build it as part of your application:

yarn add @depay/widgets

or if you use npm

npm install @depay/widgets --save

CDN​

If you don't want to install the package or don't want to build DePay Widgets as part of your application, you can also load DePay Widgets via our CDN:

<script defer async src="https://integrate.depay.com/widgets/v10.js"></script>

Usage​

After installation, import DePayWidgets from @depay/widgets wherever you need it:

import DePayWidgets from '@depay/widgets';

Configuration​

You need to pass a configuration object to DePayWidgets.Donation which needs to at least contain the accept field.

DePayWidgets.Donation({

  title: "Tip",

  accept: [{
    blockchain: 'ethereum',
    token: '0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb',
    receiver: '0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02'
  }]
});

This declares to receive DEPAY tokens (0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb) as tip on ethereum to 0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02.

You can also accept multiple tokens on multiple blockchains:

DePayWidgets.Donation({

  title: "Tip",

  accept: [
    {
      blockchain: 'ethereum',
      token: '0xdac17f958d2ee523a2206206994597c13d831ec7',
      receiver: '0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02'
    },{
      blockchain: 'bsc',
      token: '0xe9e7cea3dedca5984780bafc599bd69add087d56',
      receiver: '0x552C2a5a774CcaEeC036d41c983808E3c76477e6'
    }
  ]
});

The DePay App helps you to create a basic valid configuration: DePay App > Integrations > New Integration > Donation Widget

accept​

The accept attribute describes what is accepted as a tip. It needs to be an array and needs to contain at least one entry.

Required Attributes​

blockchain - The name of the blockchain (e.g. ethereum, bsc, polygon etc.)

token - The address of the token you want to receive

receiver - The address receiving the tip. Always double check that you've set the right address.

amount​

When you want to control how the amount selection behaves, pass the amount configuration object, alongside values for start, min and step.

start: The amount that is initially selected.

min: The minimum amount selectable.

step: The number by wich to increment/decremten changes to the amount.

{
  amount: {
    'start': 10,
    'min': 1,
    'step': 1
  }
}

connected​

A callback that will be executed once the user connects a wallet.

This function will be called with the connected wallet address as the main argument:

connected: (address)=> {
  // do something with the address
}

closed​

closed

A function that will be called once the user closes the widget (no matter if before or after the tip).

closed: ()=> {
  // do something if user closed the widget
}

before​

before

A function that will be called before the tip is handed over to the wallet.

Allows you to stop the tip if this methods returns false.

before: (tip)=> {
  alert('Something went wrong')
  return false // stop
}

sent​

sent

A function that will be called once the tip has been sent to the network (but still needs to be mined/confirmed).

The widget will call this function with a transaction as single argument (see: depay-web3-wallets for more details about the structure)

sent: (transaction)=> {
  // called when tip transaction has been sent to the network
}

succeeded​

succeeded

A function that will be called once the tip has succeeded on the network (checked client-side).

The widget will call this function passing a transaction as single argument (see: depay-web3-wallets for more details)

succeeded: (transaction)=> {
  // called when tip transaction has been confirmed once by the network
}

failed​

failed

A function that will be called if the tip execution failed on the blockchain (after it has been sent/submitted).

The widget will call this function passing a transaction as single argument (see: depay-web3-wallets for more details)

failed: (transaction)=> {
  // called when tip transaction failed on the blockchain
  // handled by the widget, no need to display anything
}

critical​

critical

A function that will be called if the widget throws an critical internal error that it can't handle and display on it's own:

critical: (error)=> {
  // render and display the error with error.toString()
}

error​

error

A function that will be called if the widget throws an non-critical internal error that it can and will handle and display on it's own:

error: (error)=> {
  // maybe do some internal tracking with error.toString()
  // no need to display anything as widget takes care of displaying the error
}

currency​

Allows you to enforce displayed local currency (instead of automatically detecting it):

{
  currency: 'USD'
}

whitelist​

Allows only the configured tokens to be eligible as means of tip (from the sender):

whitelist: {
  ethereum: [
    '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', // ETH
    '0xdac17f958d2ee523a2206206994597c13d831ec7', // USDT
    '0x6b175474e89094c44da98b954eedeac495271d0f'  // DAI
  ],
  bsc: [
    '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', // BNB
    '0xe9e7cea3dedca5984780bafc599bd69add087d56', // BUSD
    '0x55d398326f99059ff775485246999027b3197955'  // BSC-USD
  ],
  polygon: [
    '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', // MATIC
    '0x2791bca1f2de4661ed88a30c99a7a9449aa84174', // USDC
  ]
}

blacklist​

Allows to blacklist tokens so that they will not be suggested as means of tip (from the sender):

blacklist: {
  ethereum: [
    '0x82dfDB2ec1aa6003Ed4aCBa663403D7c2127Ff67',  // akSwap
    '0x1368452Bfb5Cd127971C8DE22C58fBE89D35A6BF',  // JNTR/e
    '0xC12D1c73eE7DC3615BA4e37E4ABFdbDDFA38907E',  // KICK
  ],
  bsc: [
    '0x119e2ad8f0c85c6f61afdf0df69693028cdc10be', // Zepe
    '0xb0557906c617f0048a700758606f64b33d0c41a6', // Zepe
    '0x5190b01965b6e3d786706fd4a999978626c19880', // TheEver
    '0x68d1569d1a6968f194b4d93f8d0b416c123a599f', // AABek
    '0xa2295477a3433f1d06ba349cde9f89a8b24e7f8d', // AAX
    '0xbc6675de91e3da8eac51293ecb87c359019621cf', // AIR
    '0x5558447b06867ffebd87dd63426d61c868c45904', // BNBW
    '0x569b2cf0b745ef7fad04e8ae226251814b3395f9', // BSCTOKEN
    '0x373233a38ae21cf0c4f9de11570e7d5aa6824a1e', // ALPACA
    '0x7269163f2b060fb90101f58cf724737a2759f0bb', // PUPDOGE
    '0xb16600c510b0f323dee2cb212924d90e58864421', // FLUX
    '0x2df0b14ee90671021b016dab59f2300fb08681fa', // SAFEMOON.is
    '0xd22202d23fe7de9e3dbe11a2a88f42f4cb9507cf', // MNEB
    '0xfc646d0b564bf191b3d3adf2b620a792e485e6da', // PIZA
    '0xa58950f05fea2277d2608748412bf9f802ea4901', // WSG
    '0x12e34cdf6a031a10fe241864c32fb03a4fdad739' // FREE
  ]
}

event​

If set to ifSwapped, emits an event if payments are routed through router smart contract. Payments are routed through the DePayPaymentRouter if swapping tokens is required in order to perform the payment. If payments are not routed through the router, e.g. direct transfer, no event is emited if event is set to ifSwapped.

{
  event: 'ifSwapped'
}

container​

Allows you to pass a container element that is supposed to contain the widget:

{
  container: document.getElementById('my-container')
}

Make sure to set the css value position: relative; for the container element. Otherwise it can not contain the widget.

React example:

let CustomComponentWithWidget = (props)=>{
  let container = useRef()

  useEffect(()=>{
    if(container.current) {
      DePayWidgets.Donation({ ...defaultArguments, document,
        container: container.current
      })
    }
  }, [container])

  return(
    <div ref={container} style={{ position: 'relative', border: '1px solid black', width: "600px", height: "600px" }}></div>
  )
}

style​

Allows you to change the style of the widget.

{
  style: {
    colors: {
      primary: '#ffd265',
      text: '#e1b64a',
      buttonText: '#000000',
      icons: '#ffd265'
    },
    fontFamily: '"Cardo", serif !important',
    css: `
      @import url("https://fonts.googleapis.com/css2?family=Cardo:wght@400;700&display=swap");

      .ReactDialogBackground {
        background: rgba(0,0,0,0.8);
      }
    `
  }
}

fee​

You can configure a fee which will be applied to every tip with it's own dedicated fee receiver address.

The fee will be taken from the target token and target amount (after swap, depending on your accept configuration).

amount: Either percentage (e.g. 5%, or absolute amount as BigNumber string ('100000000000000000') or pure number (2.5)

receiver: The address that is supposed to receive the fee.

{
  fee: {
    amount: '3%',
    receiver: '0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02'
  }
}

Unmount​

Allows you to unmount (the React safe way) the entire widget from the outside:

let { unmount } = await DePayWidgets.Donation({})

unmount()