Payments

The ultimate guide to integrate Web3 Payments.

Payment

BNB 0.413

DePay Payments allows you to accept and perform peer-to-peer Web3 Payments with on-the-fly any-to-anything conversion.


Preparation

In order to receive Web3 Payments on any blockchain you need to have your own wallet on that particular blockchain first:

Create an Ethereum wallet

Create a BSC wallet

If you want to receive your own token (or any token other token) as means of payment, that token needs to have a pair (liquidity pool) on one of the following decentralized exchanges with at least 10k USD reserves in order to be routable with DePay payments:

Create Uniswap v2 Liquidity Pool (Ethereum)

Create Pancakeswap Liquidity Pool (Binance Smart Chain)


Button

The DePay Payments button allows you to directly accept Web3 Payments on your website or DApp without any further installation of javascript packages. Just use our button to open a payment widget that uses your configuration.

<div
class="DePayButton"
label="Pay"
widget="Payment"
configuration='{"accept":[{"blockchain":"ethereum","amount":20,"token":"0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb","receiver":"0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02"}]}'
></div>
<script src="https://integrate.depay.fi/buttons/v6.js"></script>
<noscript><a href="https://depay.fi">Web3 Payments</a> are currently not supported without JavaScript enabled.</noscript>
<script>DePayButtons.init({document: document});</script>

Use our configurator to make sure you pass the correct configuration.


Widget

If you want to open our widget directly from your application code, use our widget library.

Installation

You can either load the @depay/widgets package via CDN:

<script src="https://integrate.depay.fi/widgets/v6.js"></script>

or you install @depay/widgets via the package manager of your choice and ship it as part of your application bundle:

yarn add @depay/widgets
npm install @depay/widgets --save

Load the DePayWidgets package wherever you need it and call the Payment method:

import DePayWidgets from '@depay/widgets';
DePayWidgets.Payment({
  accept: [{
    amount: 10,
    token: '0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb',
    blockchain: 'ethereum',
    receiver: '0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02'
  }]
});

Configuration

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

DePayWidgets.Payment({
  accept: [{
    blockchain: 'ethereum',
    amount: 20,
    token: '0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb',
    receiver: '0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02'
  }]
});

You can also accept multiple payments on multiple blockchains:

DePayWidgets.Payment({
  accept: [
    { // 20 USDT on ethereum
      blockchain: 'ethereum',
      amount: 20,
      token: '0xdac17f958d2ee523a2206206994597c13d831ec7',
      receiver: '0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02'
    },{ // 20 BUSD on bsc
      blockchain: 'bsc',
      amount: 20,
      token: '0xe9e7cea3dedca5984780bafc599bd69add087d56',
      receiver: '0x552C2a5a774CcaEeC036d41c983808E3c76477e6'
    }
  ]
});

A single payment acceptance configuration object can have the following attributes:

blockchain

Currently supported: ethereum and bsc (Binance Smart Chain)

amount

The amount of tokens you want to receive. Needs to be passed as a human-readable number e.g. 20.

The BigNumber of that amount will be calculated internally including finding the right amount of decimals for the given token. So please just pass the amount in a human readable form as Number/Decimal: e.g. 20 for 20 USDT or 20.25 etc.

If you do not pass an amount, the user will be able to select an amount within the widget.

token

The address of the token you want to receive.

receiver

The address receiving the payment. Always double check that you've set the right address.

Additional optional configuration

amount

If no amount is passed to accept, this allows you to control how the amount selection behaves, pass the amount configuration object, alongside values for start, min and step.

DePayWidgets.Payment({

  amount: {
    start: 1,
    step: 1,
    min: 1
  }
})

track

Allows to track payment confirmation via DePay to enable integration into web applications.

DePayWidgets.Payment({

  track: {
    endpoint: '/track/payments' // your endpoint to forward the payment tracking to the payments api
  }
})

Once the payment has been submitted by the widget, it will call the configured endpoint with:

POST /track/payments
BODY:
  {
    "blockchain": "ethereum",
    "transaction": "0x4311a9820195c2a5af99c45c72c88848ed403a4020863c913feed81d15855ae4",
    "sender": "0x769794c94e9f113e357023dab73e81dbd6db201c",
    "nonce": 103,
    "after_block": 13230369,
    "to_token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  }

Your endpoint needs to make sure to forward this to the payment tracking api.

Also make sure to add token , amount and confirmations when forwarding the request to the payments api. Those values are supposed to be set by your backend not the widget nor the fronted because any user could set these values to their liking otherwise, having you confirm payment amounts and tokens that you didn't intend to receive!

Make sure you read the Payment Tracking API documentation for further details on how to integrate payment tracking.

Payment tracking requests will be attempted up to 3 times by the widget and will display "Payment tracking failed!" to the user if the widget was not able to start payment tracking via the given endpoint after 3 attempts.

A failed payment tracking will also call the error callback with

{ code: "TRACKING_FAILED" }

connected

A function that will be called once the user connects a wallet.

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

DePayWidgets.Payment({

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

sent

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

The widget will call the this function passing a transaction as single argument. See: depay-web3-transaction for more details.

DePayWidgets.Payment({

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

confirmed

A function that will be called once the payment has been confirmed once by the network.

The widget will call the this function passing a transaction as single argument. See: depay-web3-transaction for more details.

DePayWidgets.Payment({

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

DePayWidgets.Payment({

  ensured: (transaction)=> {
    // called when payment transaction has been confirmed X times by the network
  }
})

failed

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

The widget will call the this function passing a transaction as single argument. See: depay-web3-transaction for more details.

DePayWidgets.Payment({

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

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:

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

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:

DePayWidgets.Payment({

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

providers

Allows to set providers to be used for making RPC calls to the individiual blockchains:

DePayWidgets.Payment({

  providers: {
    ethereum: ['http://localhost:8545'],
    bsc: ['http://localhost:8545']
  }
})

currency

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

DePayWidgets.Payment({

  currency: 'USD'

})

whitelist

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

DePayWidgets.Payment({

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

blacklist

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

DePayWidgets.Payment({
  
  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 a payment event if payments are routed through the 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.

DePayWidgets.Payment({

  event: 'ifSwapped'
  
})

style

Allows you to change the style of the widget.

DePayWidgets.Payment({
  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);
      }
    `
  }
})

colors

Allows you to set color values:

DePayWidgets.Payment({
  
  style: {
    colors: {
      primary: '#ffd265',
      text: '#ffd265',
      buttonText: '#000000',
      icons: '#ffd265'
    }
  }
})

fontFamily

Allows you to set the font-family:

DePayWidgets.Payment({
  
  style: {
    fontFamily: '"Cardo", serif !important'
  }
})

css

Allows you to inject CSS:

DePayWidgets.Payment({
  
  style: {
    css: `
      @import url("https://fonts.googleapis.com/css2?family=Cardo:wght@400;700&display=swap");

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

unmount

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

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

unmount()


Configurator

We are currently migrating the configurator...

Support

Need additional help
?

Feel free to reach out in order to get additional help:

Ask the community
Open an issue
Start a conversation