Transactions

Transactions are game-initiated payment requests created through the Funtico Payment Service Provider API. They represent purchase requests from your game to users, denominated in TICO cryptocurrency. Games use their API Key to create and manage these transactions.

Important

This page covers game-initiated transactions only. User platform transactions (deposits, transfers, etc.) are accessed separately via the transactions:read scope through the Platform API.

When a user wants to make a purchase in your game, you create a transaction using your API Key. The transaction system provides:

• Secure payment processing using TICO cryptocurrency
• Flexible item management - single items or shopping carts
• Multiple UI modes - redirect or new tab checkout experiences
• Real-time status tracking with webhook notifications
• Automatic expiration to prevent abandoned transactions

Transaction Components

Items

Each transaction contains one or more items that the user wants to purchase. Items include:

• Name and description - what the user is buying
• Image URL - visual representation of the item
• Quantity and unit price - how many and at what cost
• Currency - TICO fixed price or USD for flexible pricing based on TICO live price
• Metadata - game-specific data (XP, rarity, category, etc.)

Transaction Metadata

Games can attach custom metadata to transactions for tracking purposes:

• User identifiers
• Game session information
• Geographic data
• Custom business logic data

UI Configuration

Transactions support two checkout modes:

• Redirect mode - user is redirected to checkout and back to your game
• New tab mode - checkout opens in a new tab/window and closes when complete

Transaction Lifecycle

Transactions follow a defined state machine with clear status transitions:

stateDiagram-v2
    [*] --> created
    confirmed --> completed
    confirmed --> failed
    created --> cancelled
    created --> confirmed
    created --> expired

Status Descriptions

• created - Transaction has been created and is awaiting user confirmation
• confirmed - User has confirmed the transaction and payment is being processed
• completed - Payment successful, TICO has been deducted from user’s balance
• failed - Payment failed (insufficient balance, network issues, etc.)
• cancelled - User or game cancelled the transaction
• expired - Transaction expired due to timeout

Payment Flow

The payment flow from a game’s perspective:

sequenceDiagram
    actor U as User
    participant G as Game
    participant API as Payment API
    participant C as Checkout
    
    U->>G: Click purchase button
    G->>API: Create transaction
    API-->>G: Transaction data + checkout URL
    G->>U: Redirect to checkout URL
    U->>C: Review & confirm/cancel transaction
    C->>U: Redirect back to game
    C->>G: Webhook notification (optional)
    G->>API: Poll status (if no webhooks)

Step-by-Step Flow

1. Transaction Creation - Game creates transaction using API Key with items and configuration
2. User Redirect - Game redirects user to the provided checkout URL
3. Checkout Process - User reviews transaction and confirms/cancels (authentication handled by Funtico)
4. Return to Game - User is redirected back to game with result
5. Status Updates - Game receives webhook notifications or polls for transaction status

Integration Patterns

Polling Pattern

Games can poll the transaction status endpoint to check for updates:

• Suitable for simple integrations
• Requires regular API calls
• Good for real-time status updates

Webhook Pattern

Games can subscribe to webhook notifications:

• Automatic status updates
• No polling required
• Recommended for production applications

Transaction Expiration

All transactions have a configurable expiration time to prevent abandoned transactions from consuming resources. When a transaction expires:

• It can no longer be confirmed by the user
• The status changes to “expired”
• Games should handle expired transactions gracefully

Security Considerations

• API Key authentication - Games authenticate using secure API Keys
• User authentication handled by Funtico - Users log in through Funtico’s secure checkout
• Secure checkout - All payment processing happens on Funtico’s secure platform
• Balance verification - System checks user balance before processing payment
• Transaction isolation - Each transaction is processed independently

Error Handling

Common transaction failure scenarios:

• Insufficient balance - User doesn’t have enough TICO
• User cancellation - User explicitly cancels the transaction
• Expiration - Transaction times out before completion

Games should implement appropriate error handling to provide a smooth user experience when transactions fail.

Best Practices

• Set appropriate expiration times - Balance security with user experience
• Handle all status transitions - Don’t assume transactions always succeed
• Implement webhooks - For reliable status updates
• Provide clear user feedback - Let users know what’s happening
• Test thoroughly - Use sandbox environment for development