Overview

Overview of the Galliun Payment Protocol

Galliun Payment is a decentralized payment protocol built on Sui blockchain that enables businesses to manage payments through bills and payment requests. The protocol provides several features depending on your needs:

  • Accept Payments: Use bills to accept one-time or recurring payments

  • Request Payments: Create payment requests to specific addresses

  • Sell Products: Create products and accept payments through bills

  • Track Payments: Monitor payment activities and history

Core Protocol Concepts

Bills

The fundamental unit of payment in the protocol. Bills come in two types: one-time bills and recurring bills.

One-time Bills

A single payment obligation with specific properties:

  • Amount: Fixed total amount required for the bill

  • Creator: Address that created the bill

  • Bill Manager: Address with management privileges (can be different from creator)

  • Nominated Payers: Optional list of addresses for tracking purposes

  • Coin Type: Type of supported token accepted for payment

  • Payment Records: Tracks all payments including:

    • Payment timestamp

    • Payer address

    • Amount paid

    • Refund status

One-time Bill States

  1. INPROGRESS (Initial State)

    • Bill is active and accepting payments

    • Anyone can make payments

    • Total paid amount is tracked

  2. PAID

    • Bill has received full payment

    • Total paid amount equals bill amount

    • Ready for recipient to claim

  3. COMPLETED

    • Bill has been claimed by recipient

    • Funds transferred to recipient

    • Payment records finalized

  4. CANCELED

    • Bill has been canceled by bill manager

    • No further payments accepted

    • Existing payments can be refunded

  5. REJECTED

    • Bill has been rejected by nominated payer

    • No further payments accepted

    • Existing payments can be refunded

Recurring Bills

A subscription-style payment obligation with specific properties:

  • Amount: Fixed amount required per interval

  • Interval: Time duration between payments

  • Creator: Address that created the bill

  • Bill Manager: Address that manages the bill

  • Nominated Payers: Optional list of addresses for tracking purposes

  • Payment Tracking:

    • Paid Amount: Total amount paid

    • Pending Amount: Amount paid but not yet completing an interval

    • Completed Payments: Number of completed payment intervals

    • Expires At: Timestamp when current interval expires

Recurring Bill States

  1. INPROGRESS (Initial State)

    • Bill is active and accepting interval payments

    • Anyone can make payments

    • Tracks payment intervals and expiration

    • Manages pending and completed payments

  2. CANCELED

    • Bill has been canceled by bill manager

    • No further payments accepted

    • Existing payments can be refunded

  3. REJECTED

    • Bill has been rejected by nominated payer

    • No further payments accepted

    • Existing payments can be refunded

Payment Features

  • Open Payments: Anyone can pay the bills

  • Split Payments: Multiple payers can contribute

  • Payment Tracking: Each payment is recorded with details

  • Refund Support: Payments can be refunded if needed

  • Interval Management: (Recurring Bills)

    • Automatic interval tracking

Payment Requests

A mechanism to request payment from a specific address. A payment request represents a direct payment obligation with specific properties:

  • Amount: Fixed amount requested

  • Creator: Address that created the request

  • Receiver: Address that will receive the payment

  • Payer: Address that is responsible for paying

  • Coin Type: Type of supported token for payment

  • Bill ID: Optional reference to a bill (for organized tracking)

  • Description: Human-readable description of the request

Payment Request States

  1. PENDING (Initial State)

    • Request is active and awaiting payment

    • Only specified payer can fulfill the request

    • Payment must match requested amount and token type

  2. PAID

    • Request has been paid by the payer

    • Payment has been sent to receiver

    • Request is considered completed

  3. REJECTED

    • Request has been rejected by the payer

    • No payment can be made

    • Request is considered completed

Key Features

  • Direct Payment: One-to-one payment request between parties

  • Bill Linkage: Can be linked to a bill for tracking

  • Token Support: Uses protocol-supported tokens

  • Event Tracking: All actions emit events:

    • PAYMENT_REQUEST_CREATED: New request creation

    • PAYMENT_REQUEST_PAID: Request payment completed

    • PAYMENT_REQUEST_FAILED: Request payment failed

Products

A mechanism for creating and managing products for sale. Each product has specific properties:

  • Name: Product name

  • Description: Product description

  • Price: Fixed price in protocol-supported token

  • Creator: Address that created the product

  • Quantity: Maximum number of items that can be sold

  • Sold: Number of items already sold

Key Features

  • Inventory Management:

    • Set maximum sellable quantity

    • Track sold items

  • Purchase Tracking:

    • Purchase history per product

    • Purchase events for monitoring

    • Bill creation for each purchase

Protocol Features

Event System

The protocol emits events for tracking all major actions:

Bill Events

  • BILL_CREATED: New bill creation with details of creator, manager, amount, coin type, and nominated payers

  • BILL_PAYMENT_MADE: Payment received for a bill, includes payment index, payer, and amount

  • BILL_PAYMENT_CLAIMED: Bill manager has claimed the paid amount, includes claimed amount and fee

  • BILL_PAYMENT_REFUNDED: Payment has been refunded to payer, includes payment index and refunded amount

  • BILL_CANCELLED: Bill has been cancelled by bill manager

  • BILL_REJECTED: Bill has been rejected by a nominated payer

Recurring Bill Events

  • RECURRING_BILL_CREATED: New recurring bill creation with interval settings, amount, and nominated payers

  • RECURRING_BILL_PAYMENT_MADE: Payment received for interval, includes payment index and next expiry

  • RECURRING_BILL_PAYMENT_CLAIMED: Bill manager has claimed completed interval payments

  • RECURRING_BILL_CANCELLED: Recurring bill has been cancelled

  • RECURRING_BILL_REJECTED: Recurring bill has been rejected by nominated payer

Payment Request Events

  • PAYMENT_REQUEST_CREATED: New payment request created with creator, receiver, payer, and amount

  • PAYMENT_REQUEST_PAID: Request has been paid, includes payer and payment details

  • PAYMENT_REQUEST_REJECTED: Request has been rejected by the payer

Product Events

  • PRODUCT_CREATED: New product created with name, description, price, and quantity

  • PRODUCT_PURCHASED: Product has been bought, creates a bill and tracks buyer details

  • PRODUCT_UPDATED: Product details (name, description, price) have been updated

  • PRODUCT_QUANTITY_CHANGED: Product quantity has been modified

Integration Methods

Backend Integration

  1. TypeScript SDK

    • PaymentClient for smart contract interaction

    • Provides managers for:

      • Bill management (one-time and recurring)

      • Payment request handling

      • Product management

      • Configuration management

  2. Indexer APIs

    • Query indexed data from the protocol:

      • Bills: Query bills, activities, participants, payments

      • Payment Requests: Query requests and activities

      • Products: Query products, activities, purchases

      • Events: Query protocol events by type

      • Search: Find entities by ID

Frontend Integration

Two options for integrating the payment button:

  1. React Component

    • React hook useGalliunPayment

    • Handles:

      • Product payment flow

      • Success/error callbacks

      • Loading states

  2. JavaScript Library

    • Vanilla JavaScript implementation

    • Similar functionality as React component

    • Global GalliunPayment constructor

Both frontend options provide:

  • Product payment handling

  • Wallet connection management

  • Payment status tracking

  • Event callbacks for payment flow

Next Steps

1. SDK Documentation

Learn how to interact with the smart contract:

2. API Documentation

Understand how to query indexed data:

3. Integration Guides

Feature-based guides for common use cases:

NextOverview

Last updated