Skip to main content

How payment networks work

When a user creates and sends a request, he expects to receive the correct amount of money. But how does he keep track of the payments due and received? Request is a ledger that documents requests for payment and how to agree on their completion.

There are different methods available for the payee and payer to agree on the payment status, and that is when payment networks come into play. A payment network is a predefined set of rules on how to agree on the payment status of a specific request.

A payment network is defined by:

  • The information, defined at the request creation, necessary to be able to detect payments
  • A payment method, the method used to perform a detectable payment
  • A payment detection method, the process to determine the amount paid by the payer through the payment method

Types of payment detection#

There are three ways to get consensus on a payment status.

Address based#

For these payment networks, a request contains a payment address that is unique to the request. The balance of the request is computed by reading all the inbound transfers to the payment address. To pay the request, the payer performs a normal transfer to the payment address. Outbound transfers are not taken into consideration to compute the request's balance. The address must be created exclusively for the request since every inbound transfer to the addresses is considered a payment. For example, if a Bitcoin request is created with a payment address that has already received 1 BTC, the request balance will be 1 BTC even though the payee hasn't received any funds from the payer.

For address based payment requests, the refund address also has to be exclusive to this payment refund.

Reference based#

For these payment networks, a request contains one payment address. This address doesn't have to be exclusive to the request. The balance is computed by reading transfers to the payment address containing a specific payment reference, defined by the request ID and payment address.

For ETH, we can tag and detect the payment reference directly in the transaction, using the input data field of the transaction.

When we cannot use input data or equivalent, typically for ERC20, we use a proxy smart contract to document the payment reference. The smart contract forwards a currency transfer and stores a reference.

If you need the proxy smart contract addresses, we list the most relevant ones below.

Proxy smart contracts for ERC20:

"mainnet": {
"address": "0x5f821c20947ff9be22e823edc5b3c709b33121b3",
},
"rinkeby": {
"address": "0x162edb802fae75b9ee4288345735008ba51a4ec9",
}

Proxy smart contracts for ETH when input data cannot be used:

"mainnet": {
"address": "0x37a8f5f64f2a84f2377481537f04d2a59c9f59b6",
},
"rinkeby": {
"address": "0x9c6c7817e3679c4b3f9ef9486001eae5aaed25ff",
}

For reference based payment requests, the references for the main payment and the refund are different.

Declarative#

For these payment networks, the request doesn't require any additional data. The request's stakeholders declare sending and receiving payments or refunds manually. Optionally, the creator of the request can specify the information to describe how the payment should occur, but this data will not be used to detect the payment. The payee declares the received payments and the payer declares the received refunds. The balance of the request is the sum of declared payments minus the sum of declared refunds. The payee can also declare the sent refunds and the payer the sent payments. These declarations are used only for documentation purposes and aren't taken into consideration to compute the request balance.

This type of payment network can be used with every currency.

Currencies#

The currencies that are supported for automated payment detection are

  • Bitcoin
  • Ether
  • ERC20

Bitcoin#

A Bitcoin request requires an address based payment network. This payment network is sufficient for Bitcoin requests because generating a new address for every inbound BTC transfers is already part of Bitcoin's good practices.

Ether#

Because one Ethereum address is generally used many times to receive and send transactions, we need a way to identify payments for a specific request without having to create a new address. Therefore, we use a reference-based payment network for ether requests. Input data and proxy contract methods can be used to reference the ether transfer.

ERC20#

Request is compatible with every ERC20 currency, but some of them have to be detailed manually. We use Metamask's package eth-contract-metadata to automatically fetch smart contracts and currency codes of main currencies.

Listed ERC-20:#

  • BRBC Rubic
  • FLX Reflexer Ungovernance Token
  • RAI Rai Reflex Index
  • BASIC BASIC Token
  • DG DeGate Token
  • AVAL Avaluse
  • DRT DomRaiderToken
  • XGG 10x.gg
  • DMST DMScript
  • UBI Universal Basic Income
  • SYLO Sylo
  • stETH Liquid staked Ether 2.0
  • wstETH Wrapped liquid staked Ether 2.0
  • LDO Lido DAO Token
  • LUNA Wrapped LUNA Token
  • UST Wrapped UST Token
  • KRT Wrapped KRT Token
  • SDT Wrapped SDT Token
  • MNT Wrapped MNT Token
  • MIR Wrapped MIR Token
  • mAAPL Wrapped Mirror AAPL Token
  • mGOOGL Wrapped Mirror GOOGL Token
  • mTSLA Wrapped Mirror TSLA Token
  • mNFLX Wrapped Mirror NFLX Token
  • mQQQ Wrapped Mirror QQQ Token
  • mTWTR Wrapped Mirror TWTR Token
  • mMSFT Wrapped Mirror MSFT Token
  • mAMZN Wrapped Mirror AMZN Token
  • mBABA Wrapped Mirror BABA Token
  • mIAU Wrapped Mirror IAU Token
  • mSLV Wrapped Mirror SLV Token
  • mUSO Wrapped Mirror USO Token
  • mVIXY Wrapped Mirror VIXY Token
  • OVR OVR
  • WOO Wootrade Network
  • XOR Sora Token
  • VAL Sora Validator Token
  • RFUEL RFUEL
  • JASMY JasmyCoin
  • MDX Mandala Exchange Token
  • CRBN Carbon
  • RBC Rubic
  • DDX DerivaDAO
  • PERP Perpetual
  • PERL Perlin
  • RFI Reflect Finance
  • DUCK DLP Duck Token
  • DDIM DuckDaoDime
  • MAHA MahaDAO
  • EURe Monerium EUR
  • GBPe Monerium GBP
  • USDe Monerium USD
  • ISKe Monerium ISK
  • WISE WISE Token
  • PLOT PlotX
  • ELT ELTCOIN
  • ZAP ZAP TOKEN
  • SKL SKALE
  • USDN Neutrino USD
  • FRM Ferrum Network Token
  • IDRT Rupiah Token
  • FTM Fantom
  • REVV REVV
  • aAAVE Aave AAVE
  • aBAT Aave BAT
  • aBUSD Aave BUSD
  • aDAI Aave DAI
  • aENJ Aave ENJ
  • aKNC Aave KNC
  • aLINK Aave LINK
  • aMANA Aave MANA
  • aMKR Aave MKR
  • aREN Aave REN
  • aSNX Aave SNX
  • aSUSD Aave SUSD
  • aTUSD Aave TUSD
  • aUNI Aave UNI
  • aUSDC Aave USDC
  • aUSDT Aave USDT
  • aWBTC Aave WBTC
  • aWETH Aave WETH
  • aYFI Aave YFI
  • aZRX Aave ZRX
  • AAVE Aave
  • stAAVE Staked Aave
  • CHSB SwissBorg
  • GLM Golem Network Token
  • OCTO OctoFi
  • ORBS Orbs
  • GAME GAME Credits
  • DIA DIAdata
  • DRC Dracula
  • MTL Metal
  • KEEP KEEP
  • TBTC tBTC
  • XPR Proton
  • EWTB Energy Web Token Bridged
  • HEX HEX
  • RARI Rarible
  • SNTVT Sentivate
  • MET Metronome
  • PLDAI PoolTogether Dai
  • PLSAI PoolTogether Sai
  • BLZ Bluzelle Token
  • PLUSDC PoolTogether USDC
  • POOLZ $Poolz Finance
  • YAX yAxis
  • sYAX Staked yAxis
  • YFL YF Link
  • yYFL YFLink Staking Share
  • YFLUSD YFLink USD
  • sYFL YFLink Synthetic
  • bYFL YFLink Bond
  • YFI yearn.finance
  • rDAI rDAI
  • rSAI rSAI
  • GRID GridPlus
  • OXT Orchid
  • KEY Selfkey
  • ERT Eristica
  • USDT Tether USD
  • CHAI Chai
  • UMA UMA
  • UPX UPX Token
  • ETHBNT ETHBNT Liquidity Pool
  • ENG Enigma
  • CEL Celsius
  • BTU BTU
  • BOA BOSAGORA
  • POP POP Network Token
  • SKM Skrumble Network V2
  • ENQ Enecuum
  • ZEON ZEON Network
  • REMI REMIIT REMI Token
  • HAK Shaka
  • IOTX IoTeX
  • RAE RAE Token
  • ADXL AdEx Legacy Token
  • ADX AdEx Token
  • FNT Falcon
  • NDX nDEX
  • WBTC Wrapped BTC
  • GOLD Dragonereum Gold
  • DREAM DreamTeam Token
  • MYB MyBit
  • CVL Civil Token
  • DTH Dether
  • WIB Wibson
  • BOB Bob's Repair
  • SWM SWARM
  • ONL On.Live
  • PARETO Pareto
  • HERC Hercules
  • FOAM FOAM
  • ONE Menlo One
  • SPND Spendcoin
  • AST AirSwap Token
  • RMESH RightMesh Token
  • JOY JOYSO
  • J8T JET8 Token
  • QNT Quant Network
  • XNK Ink Protocol
  • AION Aion Network
  • ELY ELY Token
  • NCT PolySwarm Nectar
  • BOX BOX Token
  • VDOC dutyof.care Token
  • RHOC Rhoc
  • GEN DAOstack
  • DGS Dragonglass
  • OMG OmiseGO
  • QSP Quantstamp
  • CLN Colu Local Network
  • STORJ Storj
  • ZORA Zoracles
  • MANA Decentraland
  • XSC CrowdstartCoin
  • ENTRP Hut34 Entropy Token
  • HYDRO Hydro
  • PKT Playkey Token
  • ZRX 0x
  • REDC RedCab
  • MOD Modum Token
  • APPC AppCoins
  • EURS STASIS EURS Token
  • AMLT AMLT
  • SNX Synthetix Network Token
  • SUSD Synth sUSD
  • SETH Synth sETH
  • SBTC Synth sBTC
  • IQN IQeon
  • C10 CRYPTO10 Hedged
  • C20 Crypto20
  • PLAY Herocoin
  • GEE Geens Platform Token
  • MLN Melon
  • HGT HelloGold Token
  • GOLDX GOLDX
  • JET Jetcoin Institute Token
  • IND Indorse Token
  • NDC NEVERDIE Coin
  • BCPT BlockMason Credit Protocol Token
  • SPN Sapien Network Token
  • LOOM Loom Network Token
  • CELR Celer Network Token
  • GLA Gladius
  • KNC Kyber Network Crystal
  • BNT Bancor Network Token
  • LUN Lunyr Token
  • LEDU LEDU Token
  • VSL vSlice
  • BCAP Blockchain Capital
  • TIME Chronobank TIME
  • TAAS Token-as-a-Service
  • TKN Monolith TKN
  • EDG Edgeless
  • GUP Guppy
  • XAUR Xaurum
  • SWT Swarm City Token
  • TRST Trustcoin
  • ANTv1 Aragon Network Token v1
  • WINGS WINGS
  • FKX KnoxsterCoin
  • 1ST FirstBlood Token
  • RLC iExec RLC Token
  • SNGLS SingularDTV
  • ICN ICONOMI
  • DGD Digix
  • MKR Maker
  • SAI Sai Stablecoin v1.0
  • DAI Dai Stablecoin
  • AMPL Ampleforth
  • MFT Mainframe Token
  • BAT Basic Attention Token
  • BEE BEE Token
  • GNO Gnosis Token
  • LINK Chainlink Token
  • PLU Pluton
  • REP Reputation Old
  • REPv2 Reputation
  • RFR Refereum
  • NFC NoFakeCoin
  • OST Open Simple Token
  • REN Republic Token
  • renBTC renBTC
  • renZEC renZEC
  • renBCH renBCH
  • renFIL renFIL
  • GNT Golem Network Token
  • SIG Spectiv Signal Token
  • QTUM Qtum
  • CAT BitClave
  • CAG Change
  • CAN CanYaCoin
  • RVT Rivetz
  • WYV Project Wyvern Token
  • ART Maecenas ART Token
  • ZIL Zilliqa
  • BMX BitMartToken
  • VIEW Viewly
  • WETH Wrapped Ether
  • cBAT Compound Basic Attention Token
  • cDAI Compound Dai
  • cSAI Compound Sai (Legacy Dai)
  • cETH Compound Ether
  • cREP Compound Augur
  • cUSDC Compound USD Coin
  • cUSDT Compound Tether
  • cWBTC Compound Wrapped BTC
  • cZRX Compound 0x
  • COMP Compound
  • NANJ NANJCOIN
  • 0xBTC 0xBitcoin Token
  • SNT Status Network Token
  • SPANK SPANK
  • BOOTY BOOTY
  • BBK Brickblock
  • LEND ETHLend Token
  • IMP Ether Kingdoms Token
  • LIKE LikeCoin
  • BNB Binance Coin
  • VEN VeChain
  • ICX ICON
  • AERGO Aergo
  • AE Aeternity
  • PPT Populous
  • IOST IOST
  • KCS Kucoin Shares
  • MITH Mithril
  • WTC Walton
  • NMR Numeraire
  • GUSD Gemini Dollar
  • USDS StableUSD
  • USDC USD Coin
  • PNK Pinakion Token
  • FUN FunFair
  • YEED YGGDRASH YEED Token
  • DSCP Disciplina Token
  • DAY Chronologic DAY Token
  • PLAT PLATINUM
  • PAX PAX Stablecoin
  • PAXG PAX Gold
  • TUSD TrueUSD
  • BUSD Binance USD
  • MAS MidasProtocol
  • ROCK2 ICE ROCK MINING
  • POA20 POA20 Token
  • LTO LTO Network Token
  • VIDT VIDT Datalink
  • CPLO Cpollo
  • NEEO NEEO
  • NEU Neumark
  • DATA Streamr
  • CRO Crypto.com Chain
  • STAR STAR
  • SAN Santiment
  • LPT Livepeer
  • PROPS Props
  • HOT HoloToken
  • ENJ Enjin Coin
  • ELF AELF
  • WAX Wax
  • POWR PowerLedger
  • XBP BlitzPredict
  • KODA KnownOrigin
  • OGN Origin Protocol
  • OUSD Origin Dollar
  • REQ Request
  • BETHER Bethereum
  • HUNT Hunt Token
  • METM Metamorph
  • DNT district0x
  • NUSD Neutral Dollar
  • MINDS Minds
  • SOUL CryptoSoul
  • OGO Origo
  • DANK DANKToken
  • PLA PlayDapp Token
  • ROOK ROOK
  • STMX StormX Token
  • MATIC Matic Network Token
  • POLY Polymath
  • LGO LGO Token
  • LVN LivenCoin
  • LRC Loopring
  • RDN Raiden Network Token
  • LMY Lunch Money
  • TLN Trustlines Network Token
  • TOP TOP Network Token
  • FET Fetch
  • MTLX Mettalex
  • UNI Uniswap
  • YFDOT Yearn Finance Dot
  • KTON Darwinia Commitment Token
  • 2KEY TwoKeyEconomy
  • STAKE STAKE Token
  • DKA dKargo
  • RING Darwinia Network Native Token
  • ROOBEE ROOBEE
  • ZCRT ZCore Token
  • DCN Dentacoin Token
  • mUSD mStable USD
  • MTA Meta
  • PLR Pillar
  • BAL Balancer (BAL)
  • GET Guaranteed Entrance Token
  • EL Elysia
  • AUC Auctus
  • HUSD HUSD
  • BC Block-Chain.com Token
  • CVP Concentrated Voting Power
  • ANT Aragon Network Token
  • WIS Experty Wisdom Token
  • AXNv1 Axion Old
  • NEXO NEXO
  • CAMP Camp
  • ATRI Atari Token
  • AXN Axion
  • GRT Graph Token
  • REEF Reef Finance
  • DODO DODO bird
  • 1INCH 1INCH Token
  • ALEPH Aleph.im Token
  • CRU CRUST
  • BADGER BADGER
  • YLD Yield
  • USDx dForce USDx
  • QRX QuiverX
  • GLQ GraphLinq
  • NBU NBU
  • ROUTE Route
  • FWB FWB Pro
  • MATTER Antimatter
  • RNDR Render Token
  • SATT SaTT
  • DF dForce
  • VSP Vesper

REQRequest

  • Symbol: REQ
  • Decimals: 18
  • Smart contract: 0x8f8221aFbB33998d8584A2B05749bA73c37a938a

For listed ERC20 currencies, you can use the code directly.

// New request for most common currencies, such as DAI or BAT:
const request = await requestNetwork.createRequest({
paymentNetwork,
requestInfo: {
currency: 'DAI',
expectedAmount: '1000000000000000000',
payee: payeeIdentity,
payer: payerIdentity,
},
signer: payeeIdentity,
});

For additional ERC20 tokens, or specific neworks, you have to mention the contract address and network identifier.

const request = await requestNetwork.createRequest({
paymentNetwork,
requestInfo: {
currency: {
network: 'mainnet',
type: RequestLogicTypes.CURRENCY.ERC20,
value: '0xdac17f958d2ee523a2206206994597c13d831ec7', // USDT
},
expectedAmount: '1000',
payee: payeeIdentity,
payer: payerIdentity,
},
signer: payeeIdentity,
});

The most convenient way to implement ERC20 requests is with a proxy contract payment network. Note that the smart contract deployed for ERC20 tokens is different than the one deployed for ether.

ERC20 requests payment detection can also be address based, but using the proxy contract payment network is the most convenient.

Other currencies#

If you would like to create a request with a currency we don't support, you have two options: