Web3 Donation Widget

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

Example

Donation

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({

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

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

You can also accept multiple tokens on multiple blockchains:

DePayWidgets.Donation({

  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 donation. 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 donation. 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 donation).

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

before

before

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

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

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

sent

sent

A function that will be called once the donation 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 donation transaction has been sent to the network
}

succeeded

succeeded

A function that will be called once the donation 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 donation transaction has been confirmed once by the network
}

failed

failed

A function that will be called if the donation 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 donation 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 donation (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 donation (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 donation 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()