OpenPayEscrow

The OpenPayEscrow contract holds payment funds in escrow until confirmed by the platform. It handles ERC-20 token payments and native BNB payments, applies platform fees, and enforces slippage protection via the price feed. Address (BSC Testnet): 0xe50464081b781AFE101EB40bC7e68Fd017c5e8f2 Explorer: View on BscScan

Constructor

constructor(uint256 _platformFeeBps, address _feeRecipient)

Parameter	Type	Description
`_platformFeeBps`	`uint256`	Platform fee in basis points (e.g., 200 = 2%)
`_feeRecipient`	`address`	Address that receives platform fees

Payment Struct

Each payment is stored on-chain with the following fields:

struct Payment {
    bytes32 paymentId;
    address merchant;
    address payer;
    address token;       // address(0) for native BNB
    uint256 amount;      // Token amount deposited
    uint256 platformFee; // Calculated on confirmation
    uint256 usdAmount;   // USD value (6 decimal precision)
    uint256 exchangeRate;
    uint256 createdAt;
    uint256 expiresAt;
    PaymentStatus status;
}

Payment Status Enum

enum PaymentStatus {
    None,      // 0 - Does not exist
    Pending,   // 1 - Funds deposited, awaiting action
    Confirmed, // 2 - Merchant paid, fee collected
    Refunded,  // 3 - Funds returned to payer
    Expired    // 4 - Timed out, funds returned
}

Write Functions

createPayment

Create an ERC-20 token payment. The payer must have approved the escrow contract to spend the token amount beforehand.

function createPayment(
    bytes32 paymentId,
    address merchant,
    address token,
    uint256 amount,
    uint256 usdAmount,
    uint256 expiresAt
) external

Parameter	Type	Description
`paymentId`	`bytes32`	Unique payment identifier (generated off-chain)
`merchant`	`address`	Merchant wallet address
`token`	`address`	ERC-20 token address (USDT, USDC, etc.)
`amount`	`uint256`	Token amount to deposit
`usdAmount`	`uint256`	USD equivalent (for record-keeping)
`expiresAt`	`uint256`	Unix timestamp when payment expires

The payer must call token.approve(escrowAddress, amount) before calling createPayment. Otherwise the transaction will revert.

createNativePayment

Create a payment using native BNB. The BNB amount is sent as msg.value.

function createNativePayment(
    bytes32 paymentId,
    address merchant,
    uint256 usdAmount,
    uint256 expiresAt
) external payable

Parameter	Type	Description
`paymentId`	`bytes32`	Unique payment identifier
`merchant`	`address`	Merchant wallet address
`usdAmount`	`uint256`	USD equivalent
`expiresAt`	`uint256`	Unix timestamp when payment expires

confirmPayment

Confirm a pending payment. Splits funds between the merchant (minus fee) and the fee recipient. Owner only.

function confirmPayment(bytes32 paymentId) external onlyOwner

On confirmation:

Platform fee (default 2%) is sent to feeRecipient
Remaining amount is sent to the merchant
Payment status changes to Confirmed

refundPayment

Refund a pending payment back to the payer. Owner only.

function refundPayment(bytes32 paymentId) external onlyOwner

expirePayment

Expire a payment that has passed its expiresAt timestamp. Funds are returned to the payer. Owner only.

function expirePayment(bytes32 paymentId) external onlyOwner

Read Functions

getPayment

Retrieve full payment details by ID.

function getPayment(bytes32 paymentId) external view returns (Payment memory)

getQuote

Get a price quote for converting a USD amount to a specific token. Returns the token amount needed plus slippage bounds.

function getQuote(
    address token,
    uint256 usdAmount
) external view returns (
    uint256 tokenAmount,
    uint256 exchangeRate,
    uint256 minAmount,
    uint256 maxAmount
)

Return Value	Description
`tokenAmount`	Exact token amount at current price
`exchangeRate`	Current exchange rate from the price feed
`minAmount`	Minimum acceptable amount (tokenAmount - slippage)
`maxAmount`	Maximum amount (tokenAmount + slippage)

State Variables

function platformFeeBps() external view returns (uint256);  // Default: 200 (2%)
function slippageBps() external view returns (uint256);      // Default: 200 (2%)
function feeRecipient() external view returns (address);
function priceFeed() external view returns (address);

Admin Functions (Owner Only)

Function	Description
`setPlatformFee(uint256 newFeeBps)`	Set platform fee (max 1000 = 10%)
`setSlippage(uint256 newSlippageBps)`	Set slippage tolerance (max 500 = 5%)
`setFeeRecipient(address newRecipient)`	Change the fee recipient address
`setPriceFeed(address _priceFeed)`	Update the price feed contract address
`setSupportedToken(address token, bool supported)`	Enable or disable a payment token

Events

event PaymentCreated(
    bytes32 indexed paymentId,
    address indexed merchant,
    address indexed payer,
    address token,
    uint256 amount,
    uint256 usdAmount
);

event PaymentConfirmed(
    bytes32 indexed paymentId,
    address indexed merchant,
    uint256 merchantAmount,
    uint256 platformFee
);

event PaymentRefunded(
    bytes32 indexed paymentId,
    address indexed payer,
    uint256 amount
);

event PaymentExpired(
    bytes32 indexed paymentId
);

event PlatformFeeUpdated(uint256 oldFee, uint256 newFee);
event SlippageUpdated(uint256 oldSlippage, uint256 newSlippage);
event PriceFeedUpdated(address oldFeed, address newFeed);
event TokenSupported(address indexed token, bool supported);

Security

Protection	Description
ReentrancyGuard	All state-changing functions are protected against reentrancy
SafeERC20	Token transfers use OpenZeppelin SafeERC20 wrappers
Ownable	Only the contract owner can confirm, refund, or expire payments
Slippage bounds	Price quotes include min/max amounts to protect against oracle manipulation
Expiry enforcement	Payments cannot be confirmed after their expiry timestamp

Example: Reading a Payment with ethers.js

import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider("https://data-seed-prebsc-1-s1.bnbchain.org:8545");

const escrow = new ethers.Contract(
  "0xe50464081b781AFE101EB40bC7e68Fd017c5e8f2",
  [
    "function getPayment(bytes32) view returns (tuple(bytes32,address,address,address,uint256,uint256,uint256,uint256,uint256,uint256,uint8))",
    "function getQuote(address,uint256) view returns (uint256,uint256,uint256,uint256)",
  ],
  provider
);

// Get a price quote: how much USDT for $10?
const [tokenAmount, exchangeRate, minAmount, maxAmount] = await escrow.getQuote(
  "0xMockUSDTAddress",
  ethers.parseUnits("10", 6) // $10 with 6 decimal precision
);

console.log("Token amount:", ethers.formatUnits(tokenAmount, 18));
console.log("Min:", ethers.formatUnits(minAmount, 18));
console.log("Max:", ethers.formatUnits(maxAmount, 18));

​OpenPayEscrow

​Constructor

​Payment Struct

​Payment Status Enum

​Write Functions

​createPayment

​createNativePayment

​confirmPayment

​refundPayment

​expirePayment

​Read Functions

​getPayment

​getQuote

​State Variables

​Admin Functions (Owner Only)

​Events

​Security

​Example: Reading a Payment with ethers.js

OpenPayEscrow

Constructor

Payment Struct

Payment Status Enum

Write Functions

createPayment

createNativePayment

confirmPayment

refundPayment

expirePayment

Read Functions

getPayment

getQuote

State Variables

Admin Functions (Owner Only)

Events

Security

Example: Reading a Payment with ethers.js