PaymentTreasury

Handles fiat-style payments via a payment gateway. Manages payment creation, confirmation, refunds, fee disbursement, and fund withdrawal for campaigns.

Two treasury variants, one SDK methodThe paymentTreasury() method works with both on-chain implementations:

Variant	Description
PaymentTreasury	Standard payment treasury with no time restrictions. Payments can be created, confirmed, and refunded at any time while the treasury is active.
TimeConstrainedPaymentTreasury	Time-constrained variant that enforces launch-time and deadline windows on-chain. Payments can only be created within the campaign window (launch → deadline + buffer). Refunds, withdrawals, and fee disbursements are only available after launch.

Both contracts share the same ABI and the same SDK interface. Time enforcement is handled entirely on-chain — simply pass the deployed contract address regardless of which variant was deployed.

const pt = oak.paymentTreasury('0x...contractAddress');

Methods

Reads

Method	Returns	Description
`getPlatformHash()`	`Hex`	Platform hash for this treasury
`getPlatformFeePercent()`	`bigint`	Platform fee in basis points
`getRaisedAmount()`	`bigint`	Current raised amount
`getAvailableRaisedAmount()`	`bigint`	Available raised (raised minus refunded)
`getLifetimeRaisedAmount()`	`bigint`	Total ever raised
`getRefundedAmount()`	`bigint`	Total refunded amount
`getExpectedAmount()`	`bigint`	Total expected pending amount
`getPaymentData(paymentId)`	`PaymentData`	Full payment details
`cancelled()`	`boolean`	Whether the treasury is cancelled

Writes

All write methods return Promise<Hex> (transaction hash).

Method	Description
`createPayment(paymentId, buyerId, itemId, paymentToken, amount, expiration, lineItems, externalFees)`	Create a new payment
`createPaymentBatch(paymentIds, buyerIds, itemIds, paymentTokens, amounts, expirations, lineItemsArray, externalFeesArray)`	Create multiple payments in one transaction
`processCryptoPayment(paymentId, itemId, buyerAddress, paymentToken, amount, lineItems, externalFees)`	Process a crypto payment directly
`cancelPayment(paymentId)`	Cancel a pending payment
`confirmPayment(paymentId, buyerAddress)`	Confirm a payment
`confirmPaymentBatch(paymentIds, buyerAddresses)`	Confirm multiple payments in one transaction
`disburseFees()`	Disburse accumulated fees
`withdraw()`	Withdraw available funds
`claimRefund(paymentId, refundAddress)`	Claim a refund to a specific address
`claimRefundSelf(paymentId)`	Claim a refund to the caller’s address
`claimExpiredFunds()`	Claim funds from expired payments
`claimNonGoalLineItems(token)`	Claim non-goal line item funds
`pauseTreasury(message)`	Pause the treasury
`unpauseTreasury(message)`	Unpause the treasury
`cancelTreasury(message)`	Cancel the treasury

Types

LineItem

interface LineItem {
  typeId: Hex;    // bytes32 type ID registered in GlobalParams
  amount: bigint; // token amount for this line item
}

ExternalFees

interface ExternalFees {
  feeType: Hex;     // bytes32 fee type identifier
  feeAmount: bigint; // fee amount in token units
}

PaymentData

Returned by getPaymentData():

Field	Type	Description
`buyerAddress`	`Address`	Buyer’s wallet address
`buyerId`	`Hex`	Off-chain buyer identifier
`itemId`	`Hex`	Item identifier
`amount`	`bigint`	Total payment amount
`expiration`	`bigint`	Payment expiration timestamp
`isConfirmed`	`boolean`	Whether the payment is confirmed
`isCryptoPayment`	`boolean`	Whether it was a crypto payment
`lineItemCount`	`bigint`	Number of line items
`paymentToken`	`Address`	ERC-20 token used for payment
`lineItems`	`PaymentLineItem[]`	Line items with config snapshots
`externalFees`	`ExternalFees[]`	External fee entries

Usage examples

Create and confirm a payment

import { keccak256, toHex, getCurrentTimestamp, addDays } from '@oaknetwork/contracts-sdk';

const paymentId    = keccak256(toHex('payment-001'));
const buyerId      = keccak256(toHex('buyer-alice'));
const itemId       = keccak256(toHex('item-001'));
const paymentToken = '0x...tokenAddress';
const typeId       = keccak256(toHex('product-sale'));

const txHash = await pt.createPayment(
  paymentId,
  buyerId,
  itemId,
  paymentToken,
  50_000n,                          // amount
  addDays(getCurrentTimestamp(), 1), // expires in 1 day
  [{ typeId, amount: 50_000n }],    // lineItems
  [],                               // externalFees
);
await oak.waitForReceipt(txHash);

// Confirm
const confirmTx = await pt.confirmPayment(paymentId, '0x...buyerAddress');
await oak.waitForReceipt(confirmTx);

Query payment data

const payment = await pt.getPaymentData(paymentId);

console.log('Amount:', payment.amount);
console.log('Confirmed:', payment.isConfirmed);
console.log('Line items:', payment.lineItems.length);

Process a crypto payment

const txHash = await pt.processCryptoPayment(
  paymentId,
  itemId,
  '0x...buyerAddress',
  paymentToken,
  50_000n,
  [{ typeId, amount: 50_000n }],
  [],
);
await oak.waitForReceipt(txHash);

Batch operations

// Create multiple payments
const batchTx = await pt.createPaymentBatch(
  [paymentId1, paymentId2],
  [buyerId1, buyerId2],
  [itemId1, itemId2],
  [token, token],
  [10_000n, 20_000n],
  [expiration, expiration],
  [[lineItem1], [lineItem2]],
  [[], []],
);
await oak.waitForReceipt(batchTx);

// Confirm multiple payments
const confirmBatchTx = await pt.confirmPaymentBatch(
  [paymentId1, paymentId2],
  [buyer1, buyer2],
);
await oak.waitForReceipt(confirmBatchTx);

Withdraw and disburse

// Disburse accumulated fees to protocol and platform
const disburse = await pt.disburseFees();
await oak.waitForReceipt(disburse);

// Withdraw available funds to the campaign creator
const withdrawTx = await pt.withdraw();
await oak.waitForReceipt(withdrawTx);

When using a TimeConstrainedPaymentTreasury, calls made outside the allowed time window will revert on-chain. For example, createPayment() will revert if called before launch or after the deadline + buffer period.

CampaignInfo — the campaign this treasury belongs to
GlobalParams — line item types and fee configuration
TreasuryFactory — deploying treasury contracts

Getting Started

Contract Entities

Examples

Use Cases

Reference

Methods

Reads

Writes

Types

LineItem

ExternalFees

PaymentData

Usage examples

Create and confirm a payment

Query payment data

Process a crypto payment

Batch operations

Withdraw and disburse

​Methods

​Reads

​Writes

​Types

​LineItem

​ExternalFees

​PaymentData

​Usage examples

​Create and confirm a payment

​Query payment data

​Process a crypto payment

​Batch operations

​Withdraw and disburse

​Related

Methods

Reads

Writes

Types

LineItem

ExternalFees

PaymentData

Usage examples

Create and confirm a payment

Query payment data

Process a crypto payment

Batch operations

Withdraw and disburse

Related