Vendor Payment Scheduler Smart Contract

A robust Clarity smart contract for scheduling and managing vendor payments on the Stacks blockchain.

Overview

This contract enables organizations to schedule future payments to vendors, manage payment authorization, and track payment history. It provides a secure, transparent system for handling recurring or scheduled vendor payments with multi-user access control.

Features

Core Payment Management

• Schedule Payments: Create payment schedules with vendor address, amount, due date, and description
• Execute Payments: Process payments automatically when due date is reached
• Update Payments: Modify payment amounts or due dates before execution
• Cancel Payments: Deactivate scheduled payments that are no longer needed
• Batch Processing: Execute multiple payments (up to 20) in a single transaction

Access Control & Security

• Owner Privileges: Contract deployer has full administrative control
• Authorized Payers: Delegate payment execution rights to trusted addresses
• Emergency Pause: Stop all contract operations in case of emergency
• Anti-Double Payment: Prevents duplicate payment execution
• Validation Guards: Comprehensive checks on amounts, dates, and statuses

Tracking & Analytics

• Vendor Balances: Track total amounts paid and payment counts per vendor
• Payment History: Full audit trail with creation and execution timestamps
• Payment Status: Monitor active, paid, and cancelled payments

Contract Structure

Data Maps

• payments: Stores all payment schedules with details
• vendor-balances: Aggregates payment statistics per vendor
• authorized-payers: Manages payer authorization status

Error Codes

• u100: Owner-only operation
• u101: Payment not found
• u102: Unauthorized access
• u103: Invalid amount (must be > 0)
• u104: Invalid date (must be in future)
• u105: Payment already executed
• u106: Insufficient balance
• u107: Payment not yet due
• u108: Record already exists
• u109: Contract paused or payment inactive

Public Functions

Administrative Functions

authorize-payer

(authorize-payer (payer principal))

Grant payment execution rights to an address. Owner only.

revoke-payer

(revoke-payer (payer principal))

Remove payment execution rights from an address. Owner only.

toggle-contract-pause

(toggle-contract-pause)

Pause or unpause all contract operations. Owner only.

Payment Functions

schedule-payment

(schedule-payment (vendor principal) (amount uint) (due-date uint) (description (string-ascii 256)))

Create a new scheduled payment. Returns payment ID. Requires authorization.

Parameters:

• vendor: Recipient's principal address
• amount: Payment amount in microSTX (1 STX = 1,000,000 microSTX)
• due-date: Block height when payment becomes executable
• description: Payment description (max 256 characters)

execute-payment

(execute-payment (payment-id uint))

Process a scheduled payment and transfer STX to vendor. Requires authorization.

Conditions:

• Payment must exist and be active
• Current block height ≥ due date
• Payment must not be already paid
• Caller must have sufficient STX balance

cancel-payment

(cancel-payment (payment-id uint))

Deactivate a scheduled payment. Requires authorization.

update-payment-date

(update-payment-date (payment-id uint) (new-due-date uint))

Modify the due date of an unpaid payment. Requires authorization.

update-payment-amount

(update-payment-amount (payment-id uint) (new-amount uint))

Modify the amount of an unpaid payment. Requires authorization.

batch-execute-payments

(batch-execute-payments (payment-ids (list 20 uint)))

Execute multiple payments in one transaction (max 20). Requires authorization.

Read-Only Functions

get-payment

(get-payment (payment-id uint))

Retrieve complete payment details.

get-vendor-balance

(get-vendor-balance (vendor principal))

Get total paid amount and payment count for a vendor.

is-payment-due

(is-payment-due (payment-id uint))

Check if a payment is ready for execution.

is-payer-authorized

(is-payer-authorized (payer principal))

Verify if an address has payment execution rights.

get-contract-paused

(get-contract-paused)

Check if contract operations are paused.

get-next-payment-id

(get-next-payment-id)

Get the next available payment ID.

Usage Example

1. Deploy Contract

The deployer automatically becomes the contract owner.

2. Authorize Additional Payers

(contract-call? .vendor-payment-scheduler authorize-payer 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM)

3. Schedule a Payment

(contract-call? .vendor-payment-scheduler schedule-payment
  'ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC
  u5000000  ;; 5 STX
  u1000     ;; Block height 1000
  "Monthly hosting services"
)

4. Execute When Due

(contract-call? .vendor-payment-scheduler execute-payment u0)

Security Considerations

• Authorization: Always verify authorized payers before granting access
• Pause Mechanism: Use toggle-contract-pause in emergencies
• STX Balance: Ensure sufficient balance before executing payments
• Due Date Validation: Payments can only be executed after due date
• Immutable Paid Status: Once paid, payments cannot be modified

Best Practices

1. Set Realistic Due Dates: Consider blockchain confirmation times
2. Batch When Possible: Use batch-execute-payments for gas efficiency
3. Monitor Vendor Balances: Track spending per vendor
4. Regular Audits: Review scheduled payments periodically
5. Test on Testnet: Always test payment flows before mainnet deployment