First breath

DFKassa can be easy integrated to a website, a mobile/desktop app, social network bots or using by hand. To start using it, follow these steps. This sections does not cover all features so it's useful to visit Advanced guide and Reference sections next. All examples below will use native web3 libraries, not our SDK's

Note

You can use our SDK's to simplify payments receiving

• Python

Fell free to ask any questions at our Telegram Official Support Chat

---

1) Redirect user to the payment page

Redirect the buyer to the invoice payment page and provide in query string details about amount, currencies and networks you accept. Note that it's safe pass such data to mutable URL because all things will then be validated at your private side from the blockchain directly. You can check out all available params at Reference section.

Try this URL out

https://dfkassa.pages.dev/pay?
    receiver=0xF621E6645BDE67bd3BDEcFA9A674Ad5e7EDad756
    &amount=100  // (1)
    &accept=ETH/5/auto;TERC20/5/10  // (2)
    &testnets=1  // (3)
    &payload=123123  // (4)

1. Pass amount in USD for the purchase (used to auto price estimation).
2. Pass tokens and networks you accept spearated by a semicolon: currency, chain ids and amount (or auto for auto price estimation).
3. Show testnets for purchase.
4. Any custom number to determine then this payment was made for.

See How amount is calculated for custom token when its amount is auto?

2) Scan new events in blockchain

Now you can watch any incomes directly from the blockchain (you can find examples at the end of the page). You can do this using our SDKs.

Python and web3.pyTS and ethers.js

import os
import time

import web3
import dotenv


dotenv.load_dotenv()


RPC_URL = "<some websockets rpc node>"  # (1)
MY_ADDRESS = "0x123123..."  # (2)


def run_watching():
    w3 = web3.Web3(web3.WebsocketProvider(RPC_URL))
    dfkassa = w3.eth.contract(
        # Learn more about these variables
        # (3)
        address=os.getenv("DFKASSA_CONTRACT_ADDRESS_GOERLI_TESTNET"),
        abi=os.getenv("DFKASSA_CONTRACT_ABI")
    )
    oracle = w3.eth.contract(
        address=os.getenv("TOKEN_USD_ORACLE_ADDRESS_GOERLI_TESTNET"),
        abi=os.getenv("TOKEN_USD_ORACLE_CONTRACT_ABI")
    )

    events_filter = dfkassa.events.NewPayment.create_filter(
        fromBlock="latest",
        argument_filters={"merchant": MY_ADDRESS}
    )

    while True:
        for raw_event in events_filter.get_new_entries():
            receipt = w3.eth.wait_for_transaction_receipt(
                raw_event["transactionHash"])
            event = dfkassa.events.NewPayment().process_receipt(receipt)[0]

            # calcE2 returns everything in cents
            usd_token_price, usd_amount = oracle.functions.calcE2(
                event["args"]["token"],
                event["args"]["amount"]
            ).call(
                block_identifier=event["blockNumber"]
            )

            ...  # Some validations

        time.sleep(3)



if __name__ == "__main__":
    run_watching()

1. This RPC URL for Ethereum Mainnet. Check out actual RPC URLs at https://chainlist.org/. Note that you can also use your own node.
2. All payments will be recieved at this ethereum address.
3. You can use a special .env file to inject all metadata i.e. DFKassa addresses or contract ABI into your environment to any language. Find it at the end of the Refernce page.

// todo

3) Match blockchain transfer to the checkout

Now your code should determine what this payment is made for. The event will contain the payload field you used in the URL.

if event["args"]["payload"] == ...:
    ...

4) Check out currencies prices at this stamp

It's important to check actual price or its amount when the payment was done. You can do it using on-chain oracles provided by DFKassa:

Check passed amount in USD

# Suppose you expect 100$ payment and allows 3$ course movements
expected_amount = 100
allowed_difference = 3

# calcE2 returns everything in cents
usd_token_price, usd_amount = oracle.functions.calcE2(
    event["args"]["token"],
    event["args"]["amount"]
).call(
    block_identifier=event["blockNumber"]
)

if abs(expected_amount - usd_amount / 100) <= allowed_difference:
    pass

5) Make sure you accept this token

You can use token field of the event to access the token address, for example

import web3.constants


acceptable_tokens = [
    # Ether (or another native currency in other networks)
    web3.constants.ADDRESS_ZERO,

    # USDT (this address is for mainnet, not for goerli!)
    # Used as example
    "0xdAC17F958D2ee523a2206206994597C13D831ec7"
]


if event["args"]["token"] in acceptable_tokens:
    ...

6) Chill

All done! You have just recieved a cryptocurrencies payment

---

Code examples

Let us now if you want to see code examples for other languages!

Python

Setup the environment:

pip install web3 python-dotenv

import os
import time

import web3
import dotenv


dotenv.load_dotenv()


RPC_URL = "<some websockets rpc node>"  # (1)
MY_ADDRESS = "0x123123..."  # (2)


def run_watching():
    w3 = web3.Web3(web3.WebsocketProvider(RPC_URL))
    dfkassa = w3.eth.contract(
        # Learn more about these variables (3)
        address=os.getenv("DFKASSA_CONTRACT_ADDRESS_GOERLI_TESTNET"),
        abi=os.getenv("DFKASSA_CONTRACT_ABI")
    )
    oracle = w3.eth.contract(
        address=os.getenv("TOKEN_USD_ORACLE_ADDRESS_GOERLI_TESTNET"),
        abi=os.getenv("TOKEN_USD_ORACLE_CONTRACT_ABI")
    )

    events_filter = dfkassa.events.NewPayment.create_filter(
        fromBlock="latest",
        argument_filters={"merchant": MY_ADDRESS}
    )

    while True:
        for raw_event in events_filter.get_new_entries():
            receipt = w3.eth.wait_for_transaction_receipt(
                raw_event["transactionHash"])
            event = dfkassa.events.NewPayment().process_receipt(receipt)[0]

            # calcE2 returns everything in cents
            usd_token_price, usd_amount = oracle.functions.calcE2(
                event["args"]["token"],
                event["args"]["amount"]
            ).call(
                block_identifier=event["blockNumber"]
            )

            print("[ New Payment ]")
            print("USD amount:", usd_amount / 100)
            print("Payload to identify client (payment ID):", event["args"]["payload"])
            print("Event details:", event)

        time.sleep(3)



if __name__ == "__main__":
    run_watching()

1. Any WebSockets rpc url for the chain.
2. Your address to receive funds.

Output:

[ New Payment ]
USD amount: 99.99
Payload to identify client (payment ID): 0
Event details: AttributeDict({'args': AttributeDict({'payload': 0, 'merchant': '0xF621E6645BDE67bd3BDEcFA9A674Ad5e7EDad756', 'amount': 55014578863398800, 'token': '0x0000000000000000000000000000000000000000', 'tips': [AttributeDict({'reciever': '0x13BCAC23aC6916a348E2E61f0aCa7Fb3713b058A', 'amount': 316739365560000})]}), 'event': 'NewPayment', 'logIndex': 153, 'transactionIndex': 95, 'transactionHash': HexBytes('0xe2a8e127f94ed64421b90d3b9517269e1914e07554277c17dbf45689c1c2c71d'), 'address': '0xeDB7a8A4d2189Cc632AF6AcaFE6eE81239C2C7df', 'blockHash': HexBytes('0x7b892eb067a2c6531b1f6a611880bd488dc28b1530dc8b8b2c6ca832a67fae71'), 'blockNumber': 8756537})