> For the complete documentation index, see [llms.txt](https://galliun-1.gitbook.io/galliun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://galliun-1.gitbook.io/galliun/overview.md). # Overview 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: * [Getting Started](/galliun/sdk-reference/getting-started.md) - SDK setup and initialization * [Bill Management](/galliun/sdk-reference/bill-management.md) - Create and manage bills * [Payment Requests](/galliun/sdk-reference/payment-requests.md) - Handle payment requests * [Product Management](/galliun/sdk-reference/product-management.md) - Manage products ### 2. API Documentation Understand how to query indexed data: * [API Overview](/galliun/api-reference/overview.md) - API basics and authentication * [Bills API](/galliun/api-reference/bills.md) - Query bills and activities * [Payment Requests API](/galliun/api-reference/payment-requests.md) - Query payment requests * [Products API](/galliun/api-reference/products.md) - Query products and purchases * [Events API](/galliun/api-reference/events.md) - Track protocol events ### 3. Integration Guides Feature-based guides for common use cases: * [One-time Bill Integration](https://github.com/Galliun/GallyPay/blob/main/docs/gitbook/integration/one-time-bill.md) - Accept one-time payments * [Recurring Bill Integration](https://github.com/Galliun/GallyPay/blob/main/docs/gitbook/integration/recurring-bill.md) - Set up subscriptions * [Payment Request Integration](https://github.com/Galliun/GallyPay/blob/main/docs/gitbook/integration/payment-request.md) - Request payments * [Product Integration](https://github.com/Galliun/GallyPay/blob/main/docs/gitbook/integration/product.md) - Sell products * [Pay Button Integration](https://github.com/Galliun/GallyPay/blob/main/docs/gitbook/integration/pay-button.md) - Add payment button