Smart Contract Integration

This guide is for developers who want to integrate MakaPay at the smart contract level. Learn how to receive on-chain callbacks when payments are processed, enabling fully automated and trustless payment flows.

Overview

MakaPay V4 smart contracts provide:

CREATE2 Deterministic Addresses: Payment addresses are computed before deployment
On-Chain Callbacks: Your contract can receive notifications when payments arrive
Frontrun Protection: Fee amounts are baked into the address computation
Cross-Chain Recovery: Same address works on all EVM chains

┌─────────────────────────────────────────────────────────────────┐
│                     Payment Flow (V4)                           │
│                                                                 │
│  1. Compute Address ──→ 2. Customer Pays ──→ 3. Process Payment │
│                                                     │           │
│                                                     ▼           │
│                                           4. Callback to Your   │
│                                              Contract (optional)│
└─────────────────────────────────────────────────────────────────┘

The `onPaymentReceived` Callback

The most powerful feature for developers is the optional callback that V4 contracts can trigger when a payment is processed. If your merchant address is a smart contract that implements the callback interface, it will be called automatically.

Interface

interface IPaymentReceiverV4 {
    /**
     * @notice Called when payment is processed and funds are sent to this contract
     * @param data Arbitrary callback data (set when payment is created)
     * @param token The token address that was received
     * @param amount Total amount that was in the payment wallet
     * @param fee Fee amount that was deducted (0 if no fee)
     */
    function onPaymentReceived(
        bytes calldata data,
        address token,
        uint256 amount,
        uint256 fee
    ) external;
}

When Is It Called?

The callback is triggered when all of these conditions are met:

The payment is processed via PaymentWalletFactoryV4.process() or processNoFee()
The merchant address has contract code (is a smart contract)
The callbackData parameter is non-empty

Callback Data

The callbackData is arbitrary bytes that you define when creating the payment. This allows you to pass context to your contract, such as:

Order IDs
User identifiers
Product SKUs
Subscription IDs
Any custom data your application needs

Real-World Example: Gas Tank Deposits

MakaPay uses its own V4 callback system for the Gas Tank. Here's how the GasTankV4 contract receives deposit notifications:

How It Works

Payment Created: A deposit payment is created with merchant = GasTank contract address
User Sends USDT: User sends USDT to the computed payment address
Payment Processed: MakaPay calls factory.process() with callback data
Callback Triggered: GasTank's onPaymentReceived() is called
Balance Updated: User's Gas Tank balance is credited automatically

GasTank Implementation

contract GasTankV4 {
    mapping(string => uint256) public userBalances;

    /**
     * @notice Callback from PaymentWalletV4 when deposit is processed
     * @param data Encoded (orderId, userId)
     * @param token Token received (must be USDT)
     * @param amount Total amount deposited
     * @param fee Fee deducted (should be 0 for deposits)
     */
    function onPaymentReceived(
        bytes calldata data,
        address token,
        uint256 amount,
        uint256 fee
    ) external {
        // Decode the callback data
        (string memory orderId, string memory userId) = abi.decode(
            data,
            (string, string)
        );

        // Verify caller is a legitimate payment wallet
        address expectedWallet = paymentFactory.computeAddress(
            orderId,
            address(this),  // merchant = this contract
            token,
            address(0),     // feeRecipient
            0               // feeAmount
        );
        require(msg.sender == expectedWallet, "Untrusted caller");

        // Credit user's balance
        uint256 depositAmount = amount - fee;
        userBalances[userId] += depositAmount;

        emit Deposited(userId, depositAmount, orderId);
    }
}

Key Security Pattern

Notice how the GasTank verifies the caller:

address expectedWallet = paymentFactory.computeAddress(...);
require(msg.sender == expectedWallet, "Untrusted caller");

This is critical. Since anyone can call your onPaymentReceived() function, you must verify that the caller is a legitimate payment wallet. The CREATE2 computation ensures only the correct wallet can produce a matching address.

Use Case Examples

1. Automated Subscription Service

contract SubscriptionService is IPaymentReceiverV4 {
    struct Subscription {
        uint256 expiresAt;
        string tier;
    }

    mapping(address => Subscription) public subscriptions;

    function onPaymentReceived(
        bytes calldata data,
        address token,
        uint256 amount,
        uint256 fee
    ) external {
        // Verify caller (see security pattern above)

        // Decode subscription data
        (address user, string memory tier, uint256 duration) = abi.decode(
            data,
            (address, string, uint256)
        );

        // Extend subscription
        uint256 currentExpiry = subscriptions[user].expiresAt;
        if (currentExpiry < block.timestamp) {
            currentExpiry = block.timestamp;
        }

        subscriptions[user] = Subscription({
            expiresAt: currentExpiry + duration,
            tier: tier
        });

        emit SubscriptionExtended(user, tier, duration);
    }
}

2. NFT Minting on Payment

contract NFTSale is IPaymentReceiverV4, ERC721 {
    uint256 public nextTokenId;
    uint256 public price;

    function onPaymentReceived(
        bytes calldata data,
        address token,
        uint256 amount,
        uint256 fee
    ) external {
        // Verify caller

        // Decode recipient
        address recipient = abi.decode(data, (address));

        // Verify payment amount
        require(amount - fee >= price, "Insufficient payment");

        // Mint NFT
        _mint(recipient, nextTokenId++);
    }
}

3. Escrow Release

contract Escrow is IPaymentReceiverV4 {
    struct Deal {
        address buyer;
        address seller;
        uint256 amount;
        bool funded;
    }

    mapping(bytes32 => Deal) public deals;

    function onPaymentReceived(
        bytes calldata data,
        address token,
        uint256 amount,
        uint256 fee
    ) external {
        // Verify caller

        bytes32 dealId = abi.decode(data, (bytes32));
        Deal storage deal = deals[dealId];

        require(!deal.funded, "Already funded");
        require(amount - fee >= deal.amount, "Insufficient");

        deal.funded = true;
        emit DealFunded(dealId, amount - fee);
    }

    function releaseFunds(bytes32 dealId) external {
        // Release logic...
    }
}

4. DAO Treasury Deposits

contract DAOTreasury is IPaymentReceiverV4 {
    mapping(address => uint256) public contributions;
    uint256 public totalContributions;

    function onPaymentReceived(
        bytes calldata data,
        address token,
        uint256 amount,
        uint256 fee
    ) external {
        // Verify caller

        address contributor = abi.decode(data, (address));
        uint256 netAmount = amount - fee;

        contributions[contributor] += netAmount;
        totalContributions += netAmount;

        emit ContributionReceived(contributor, netAmount);
    }
}

CREATE2 Deterministic Addresses

How Address Computation Works

V4 uses CREATE2 to compute payment addresses before any contract is deployed:

// Salt includes ALL payment parameters
bytes32 salt = keccak256(abi.encodePacked(
    orderId,
    merchant,
    token,
    feeRecipient,
    feeAmount
));

// Address computed using CREATE2 formula
address wallet = address(uint160(uint256(keccak256(abi.encodePacked(
    bytes1(0xff),
    factoryAddress,
    salt,
    proxyBytecodeHash
)))));

Why This Matters

Pre-Computed: Address is known before deployment
Deterministic: Same inputs always produce same address
Frontrun Resistant: Fee amount is part of the salt (V4 upgrade)
Cross-Chain: Same address on all EVM chains

Computing Addresses Off-Chain

import { ethers } from 'ethers';

async function computePaymentAddress(factory, params) {
    const { orderId, merchant, token, feeRecipient, feeAmount } = params;

    return await factory.computeAddress(
        orderId,
        merchant,
        token,
        feeRecipient,
        feeAmount
    );
}

// Example usage
const address = await computePaymentAddress(factory, {
    orderId: "order_12345",
    merchant: "0xYourContract...",
    token: USDT_ADDRESS,
    feeRecipient: FEE_COLLECTOR,
    feeAmount: ethers.parseUnits("1.13", 6)  // 6 decimals for USDT
});

console.log("Send payment to:", address);

V4 Contract Reference

PaymentWalletFactoryV4

The main entry point for all payment operations.

`computeAddress()`

function computeAddress(
    string calldata orderId,
    address merchant,
    address token,
    address feeRecipient,
    uint256 feeAmount
) external view returns (address)

Pre-computes the payment wallet address.

`process()`

function process(
    string calldata orderId,
    address merchant,
    address token,
    address feeRecipient,
    uint256 feeAmount,
    bytes calldata callbackData
) external returns (address wallet, uint256 amount)

Processes a payment with the committed fee. Use for normal payments.

Parameters:

callbackData: If non-empty and merchant is a contract, triggers onPaymentReceived()

`processNoFee()`

function processNoFee(
    string calldata orderId,
    address merchant,
    address token,
    address tokenToWithdraw,
    address feeRecipient,
    uint256 feeAmount,
    bytes calldata callbackData
) external returns (address wallet, uint256 amount)

Processes without taking fee. Use for:

Underpayments
Wrong token recovery
Gas Tank scenarios

`getWalletStatus()`

function getWalletStatus(
    string calldata orderId,
    address merchant,
    address token,
    address feeRecipient,
    uint256 feeAmount,
    address tokenToCheck
) external view returns (
    address wallet,
    bool exists,
    uint256 balance
)

Check if a wallet exists and its balance.

PaymentWalletV4

Minimal proxy wallet that receives and forwards payments.

`execute()`

function execute(
    address token,
    address to,
    uint256 fee,
    address feeRecipient,
    bytes calldata callbackData
) external returns (uint256 amount)

Called by factory only. Transfers funds and optionally triggers callback.

Security Considerations

1. Always Verify the Caller

Your onPaymentReceived() can be called by anyone. Always verify:

function onPaymentReceived(...) external {
    // Compute what the wallet address SHOULD be
    address expectedWallet = factory.computeAddress(
        orderId,
        address(this),
        token,
        feeRecipient,
        feeAmount
    );

    // Verify caller matches
    require(msg.sender == expectedWallet, "Untrusted caller");

    // Now safe to process...
}

2. Handle Reentrancy

Use nonReentrant modifier if your callback updates state:

import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";

contract MyContract is ReentrancyGuard, IPaymentReceiverV4 {
    function onPaymentReceived(...) external nonReentrant {
        // Safe from reentrancy
    }
}

3. Validate Token Address

Don't blindly trust the token parameter:

function onPaymentReceived(
    bytes calldata data,
    address token,
    uint256 amount,
    uint256 fee
) external {
    require(token == ACCEPTED_TOKEN, "Wrong token");
    // ...
}

4. Callback Failures Revert Everything

If your callback reverts, the entire payment transaction reverts. Make sure your callback logic is robust:

// BAD: Could revert and block payment
function onPaymentReceived(...) external {
    require(someUnreliableCondition, "Failed");  // Risky!
}

// GOOD: Graceful handling
function onPaymentReceived(...) external {
    // Store for later processing if complex logic needed
    pendingPayments[orderId] = PaymentData({...});
    emit PaymentQueued(orderId);
}

Integration Checklist

Before going live with smart contract integration:

Implement IPaymentReceiverV4 interface
Add caller verification using computeAddress()
Add reentrancy protection
Validate token addresses
Handle callback data decoding errors gracefully
Test with small amounts first
Test failure scenarios (insufficient payment, wrong token)
Audit your contract

Deployed Contract Addresses

MakaChain Mainnet (Chain ID: 777178)

Contract

Address

PaymentWalletFactoryV4

0xCB45Df5057b9a287F9b95Af7ccdC49A1C9F2fcfA

PaymentWalletV4 Implementation

0x0e77A0A5845C49EbC8EEA521024b5a04F7B0E20B

GasTankV4

0xE94EB77a80BddD3a1c1813ed17894af0a3837d2C

USDT

0x30C28E393E0732335235685B345c95E6465Ad8A5

Other Chains

Factory and implementation addresses are identical across all supported chains (Ethereum, Polygon, BSC) due to CREATE2 deployment.

Need Help?

Technical Support: [email protected]
Documentation: https://docs.makapay.io
GitHub: https://github.com/makapay

PreviousWebhooks NextTechnical Architecture

Last updated 21 days ago

Good morning

hashtagOverview

hashtagThe onPaymentReceived Callback

hashtagInterface

hashtagWhen Is It Called?

hashtagCallback Data

hashtagReal-World Example: Gas Tank Deposits

hashtagHow It Works

hashtagGasTank Implementation

hashtagKey Security Pattern

hashtagUse Case Examples

hashtag1. Automated Subscription Service

hashtag2. NFT Minting on Payment

hashtag3. Escrow Release

hashtag4. DAO Treasury Deposits

hashtagCREATE2 Deterministic Addresses

hashtagHow Address Computation Works

hashtagWhy This Matters

hashtagComputing Addresses Off-Chain

hashtagV4 Contract Reference

hashtagPaymentWalletFactoryV4

hashtagcomputeAddress()

hashtagprocess()

hashtagprocessNoFee()

hashtaggetWalletStatus()

hashtagPaymentWalletV4

hashtagexecute()

hashtagSecurity Considerations

hashtag1. Always Verify the Caller

hashtag2. Handle Reentrancy

hashtag3. Validate Token Address

hashtag4. Callback Failures Revert Everything

hashtagIntegration Checklist

hashtagDeployed Contract Addresses

hashtagMakaChain Mainnet (Chain ID: 777178)

hashtagOther Chains

hashtagNeed Help?

Overview

The `onPaymentReceived` Callback

Interface

When Is It Called?

Callback Data

Real-World Example: Gas Tank Deposits

How It Works

GasTank Implementation

Key Security Pattern

Use Case Examples

1. Automated Subscription Service

2. NFT Minting on Payment

3. Escrow Release

4. DAO Treasury Deposits

CREATE2 Deterministic Addresses

How Address Computation Works

Why This Matters

Computing Addresses Off-Chain

V4 Contract Reference

PaymentWalletFactoryV4

`computeAddress()`

`process()`

`processNoFee()`

`getWalletStatus()`

PaymentWalletV4

`execute()`

Security Considerations

1. Always Verify the Caller

2. Handle Reentrancy

3. Validate Token Address

4. Callback Failures Revert Everything

Integration Checklist

Deployed Contract Addresses

MakaChain Mainnet (Chain ID: 777178)

Other Chains

Need Help?