Skip to content

Commit 6158c7d

Browse files
claudeYun
claude
and
Yun
committed
Add documentation for multichain purchase flow
- Add new purchasing.md guide covering starterpack and credit purchases - Document openPurchaseCredits() and openStarterPack() API methods - Update overview to include monetization features - Add purchase integration to getting started guide - Update sidebar navigation to include new pages Co-authored-by: Yun <undefined@users.noreply.github.com>
1 parent 459ff2e commit 6158c7d

File tree

5 files changed

+290
-0
lines changed

5 files changed

+290
-0
lines changed

‎src/pages/controller/configuration.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,3 +86,30 @@ const sessionController = new Controller({
8686
}
8787
});
8888
```
89+
90+
## Purchase Methods
91+
92+
Controller includes built-in methods for opening purchase interfaces:
93+
94+
### openPurchaseCredits()
95+
96+
Opens the credit purchase flow, allowing users to buy credits for gasless transactions and platform services.
97+
98+
```typescript
99+
controller.openPurchaseCredits();
100+
```
101+
102+
### openStarterPack(starterpackId: string)
103+
104+
Opens the starterpack purchase interface for a specific bundle.
105+
106+
```typescript
107+
controller.openStarterPack("starterpack-id-123");
108+
```
109+
110+
Both methods support:
111+
- Credit card payments via Stripe
112+
- Cryptocurrency payments across multiple networks (Starknet, Base, Solana)
113+
- Integration with popular wallets (Argent, MetaMask, Rabby, Phantom)
114+
115+
For detailed integration guidance, see the [Purchase Integration](/controller/purchasing.md) guide.

‎src/pages/controller/getting-started.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,7 @@ Cartridge Controller in your preferred environment.
172172

173173
- Learn about [Session Keys](/controller/sessions.md)
174174
- Set up [Multiple Signers](/controller/signer-management.md) for backup authentication
175+
- Integrate [Purchase Functionality](/controller/purchasing.md) for game monetization
175176
- Customize your [Controller](/controller/presets.md)
176177
- Set up [Usernames](/controller/usernames.md)
177178
- Configure [Paymaster](/controller/configuration.md)

‎src/pages/controller/overview.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,11 @@ title: Controller Overview
4343
- Built-in achievement system for tracking player accomplishments
4444
- Reputation system that grows as players engage with games
4545
- Social features to connect players and build communities
46+
47+
### Monetization and Payments
48+
49+
- Built-in purchase system for seamless game monetization
50+
- Starterpack bundles combining credits and game assets
51+
- Multi-chain cryptocurrency payment support (Starknet, Base, Solana)
52+
- Traditional payment methods via secure credit card processing
53+
- Popular wallet integrations (Argent, MetaMask, Rabby, Phantom)

‎src/pages/controller/purchasing.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
---
2+
description: Learn how to integrate Cartridge Controller's purchase and monetization features, including starterpack purchases and credit transactions using multiple payment methods.
3+
title: Purchase Integration
4+
---
5+
6+
# Purchase Integration
7+
8+
Cartridge Controller provides built-in purchase functionality that enables seamless monetization for games and applications. The purchase system supports both traditional payment methods (credit cards) and cryptocurrency transactions across multiple blockchain networks.
9+
10+
## Overview
11+
12+
The purchase system includes:
13+
14+
- **Starterpack Purchases**: Pre-configured bundles of game assets and credits
15+
- **Credit Purchases**: Direct credit top-ups for gasless transactions
16+
- **Multichain Payment Support**: Accept payments on Starknet, Ethereum (Base), and Solana
17+
- **Multiple Wallet Integration**: Support for popular wallets across different ecosystems
18+
- **Dual Payment Methods**: Both fiat (credit card) and crypto payment options
19+
20+
## Quick Start
21+
22+
### Opening Purchase Flows
23+
24+
Controller provides simple methods to open purchase interfaces:
25+
26+
```typescript
27+
import Controller from "@cartridge/controller";
28+
29+
const controller = new Controller();
30+
31+
// Open credit purchase flow
32+
controller.openPurchaseCredits();
33+
34+
// Open starterpack purchase flow
35+
controller.openStarterPack("starterpack-id-123");
36+
```
37+
38+
## API Reference
39+
40+
### openPurchaseCredits()
41+
42+
Opens the credit purchase interface, allowing users to buy credits for gasless transactions and other platform services.
43+
44+
```typescript
45+
controller.openPurchaseCredits();
46+
```
47+
48+
**Parameters:** None
49+
50+
**Returns:** `void`
51+
52+
**Usage Example:**
53+
```typescript
54+
// In a game's UI, add a "Buy Credits" button
55+
const handleBuyCredits = () => {
56+
controller.openPurchaseCredits();
57+
};
58+
```
59+
60+
### openStarterPack(starterpackId: string)
61+
62+
Opens the starterpack purchase interface for a specific starterpack bundle.
63+
64+
```typescript
65+
controller.openStarterPack(starterpackId: string);
66+
```
67+
68+
**Parameters:**
69+
- `starterpackId` (string): The unique identifier for the starterpack to purchase
70+
71+
**Returns:** `void`
72+
73+
**Usage Example:**
74+
```typescript
75+
// Offer starterpack to new players
76+
const handleBuyStarterpack = () => {
77+
controller.openStarterPack("beginner-pack-2024");
78+
};
79+
```
80+
81+
## Supported Payment Methods
82+
83+
### Credit Card Payments
84+
85+
- Powered by Stripe for secure processing
86+
- Supports major credit and debit cards
87+
- Automatic currency conversion
88+
- PCI-compliant payment handling
89+
90+
### Cryptocurrency Payments
91+
92+
The system supports crypto payments across multiple networks:
93+
94+
#### Starknet
95+
- **Supported Wallets**: Argent
96+
- **Network**: Starknet mainnet and testnets
97+
- **Assets**: ETH, STRK, and other Starknet tokens
98+
99+
#### Ethereum (Base Network)
100+
- **Supported Wallets**: MetaMask, Rabby
101+
- **Network**: Base (Ethereum L2)
102+
- **Assets**: ETH, USDC, and other Base-compatible tokens
103+
104+
#### Solana
105+
- **Supported Wallets**: Phantom
106+
- **Network**: Solana mainnet
107+
- **Assets**: SOL, USDC, and other Solana tokens
108+
109+
## Purchase Flow
110+
111+
The purchase process follows these steps:
112+
113+
1. **Item Selection**: User selects starterpack or credit amount
114+
2. **Payment Method**: Choose between credit card or cryptocurrency
115+
3. **Wallet Connection**: For crypto payments, connect external wallet
116+
4. **Network Selection**: Choose blockchain network for crypto payments
117+
5. **Transaction Processing**: Complete payment through selected method
118+
6. **Confirmation**: Receive purchase confirmation and assets
119+
120+
## Integration Examples
121+
122+
### Basic Starterpack Integration
123+
124+
```typescript
125+
import Controller from "@cartridge/controller";
126+
127+
const controller = new Controller();
128+
129+
// Display starterpack offer to new users
130+
function showStarterpackOffer() {
131+
return (
132+
<div className="starterpack-offer">
133+
<h3>Welcome Pack</h3>
134+
<p>Get started with 1000 credits and exclusive items!</p>
135+
<button
136+
onClick={() => controller.openStarterPack("welcome-pack-2024")}
137+
className="buy-button"
138+
>
139+
Buy Welcome Pack - $9.99
140+
</button>
141+
</div>
142+
);
143+
}
144+
```
145+
146+
### Credit Top-up Integration
147+
148+
```typescript
149+
// Add credit purchase option to game UI
150+
function CreditDisplay({ credits }: { credits: number }) {
151+
return (
152+
<div className="credit-display">
153+
<span>Credits: {credits}</span>
154+
<button
155+
onClick={() => controller.openPurchaseCredits()}
156+
className="top-up-button"
157+
>
158+
+ Add Credits
159+
</button>
160+
</div>
161+
);
162+
}
163+
```
164+
165+
### Conditional Purchase Offers
166+
167+
```typescript
168+
// Show purchase options based on game state
169+
function PurchaseIntegration({ playerLevel, credits }: { playerLevel: number, credits: number }) {
170+
const showStarterpack = playerLevel < 5;
171+
const showCredits = credits < 100;
172+
173+
return (
174+
<div className="purchase-options">
175+
{showStarterpack && (
176+
<button onClick={() => controller.openStarterPack("beginner-pack")}>
177+
Beginner Pack ($4.99)
178+
</button>
179+
)}
180+
181+
{showCredits && (
182+
<button onClick={() => controller.openPurchaseCredits()}>
183+
Buy Credits
184+
</button>
185+
)}
186+
</div>
187+
);
188+
}
189+
```
190+
191+
## Best Practices
192+
193+
### User Experience
194+
- **Clear Value Proposition**: Clearly communicate what users receive with each purchase
195+
- **Strategic Timing**: Show purchase options at natural moments (low credits, level milestones)
196+
- **Multiple Options**: Offer both individual credits and value bundles through starterpacks
197+
- **Payment Choice**: Let users choose their preferred payment method
198+
199+
### Integration Guidelines
200+
- **Non-intrusive**: Don't block gameplay with purchase prompts
201+
- **Contextual**: Show relevant purchase options based on user needs
202+
- **Progressive**: Start with smaller purchases and gradually introduce larger bundles
203+
- **Accessible**: Ensure purchase buttons are easily discoverable but not overwhelming
204+
205+
### Security Considerations
206+
- **Client-side Only**: Purchase methods only open interfaces; no sensitive operations in frontend code
207+
- **Secure Handling**: All payment processing happens within Controller's secure iframe
208+
- **User Control**: Users maintain control over all payment authorizations
209+
210+
## Troubleshooting
211+
212+
### Common Issues
213+
214+
**Purchase interface doesn't open**
215+
- Ensure Controller is properly initialized and connected
216+
- Verify the user is authenticated
217+
- Check browser console for any JavaScript errors
218+
219+
**Starterpack not found**
220+
- Verify the starterpack ID exists and is active
221+
- Check that the starterpack is available in the current environment (mainnet/testnet)
222+
223+
**Wallet connection fails during crypto payment**
224+
- Ensure the wallet extension is installed and unlocked
225+
- Verify the wallet supports the selected network
226+
- Check that the user has sufficient balance for the transaction
227+
228+
**Payment processing errors**
229+
- For credit card issues, users should check their card details and limits
230+
- For crypto payments, verify network connectivity and gas/fee availability
231+
- Ensure the user completes the full payment flow without closing the interface
232+
233+
### Getting Help
234+
235+
If you encounter issues with purchase integration:
236+
- Check the browser console for detailed error messages
237+
- Verify your Controller setup matches the [getting started guide](/controller/getting-started.mdx)
238+
- Ensure you're using the latest version of the Controller SDK
239+
- Review [external wallet setup](/controller/signer-management.md) for wallet-related issues
240+
241+
## Next Steps
242+
243+
- Learn about [Session Keys](/controller/sessions.md) for gasless gaming experiences
244+
- Explore [Controller Configuration](/controller/configuration.md) options
245+
- Set up [External Wallet Integration](/controller/signer-management.md)
246+
- Review [Paymaster Configuration](/slot/paymaster.md) for gasless transactions

‎vocs.config.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,10 +68,18 @@ export default defineConfig({
6868
text: "Passkey Support",
6969
link: "/controller/passkey-support",
7070
},
71+
{
72+
text: "Signer Management",
73+
link: "/controller/signer-management",
74+
},
7175
{
7276
text: "Configuration",
7377
link: "/controller/configuration",
7478
},
79+
{
80+
text: "Purchase Integration",
81+
link: "/controller/purchasing",
82+
},
7583
{
7684
text: "Sessions",
7785
link: "/controller/sessions",

0 commit comments

Comments
 (0)