diff --git a/SUMMARY.md b/SUMMARY.md index 20ee051..abdeb4b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -2,12 +2,16 @@ - [๐Ÿงพ Rozo - Stablecoin Abstraction](README.md) - [Rozo - Visa for stablecoins](rozo-visa-for-stablecoins.md) -- [Rozo - Intent Pay SDK](intent-pay/README.md) +- [Rozo - Intent Pay](intent-pay/README.md) - [Quick Start Guide](intent-pay/quick-start.md) - [Complete Examples](intent-pay/examples.md) - [API Reference](intent-pay/api-reference.md) - [Troubleshooting](intent-pay/troubleshooting.md) - [AI Prompts](intent-pay/ai-prompts.md) + - [Intent API](intent-pay/API/README.md) + - [Endpoints](intent-pay/API/endpoints.md) + - [Payment Bridging](intent-pay/API/payment-bridging.md) + - [Types](intent-pay/API/types.md) - [API Doc](api-doc/README.md) - [Make a Payment (Sign)](api-doc/make-a-payment-sign.md) - [Payment (Cashback Sign)](api-doc/payment-cashback-sign.md) diff --git a/intent-pay/API/README.md b/intent-pay/API/README.md new file mode 100644 index 0000000..1d43f1a --- /dev/null +++ b/intent-pay/API/README.md @@ -0,0 +1,73 @@ +# Rozo Payment API + +Backend-focused API documentation for creating, managing, and tracking payments through the Intent Pay system. + +**Base URL:** `https://intentapi.rozo.ai` + +## Documentation Structure + +- [API Endpoints](./endpoints.md) - REST API reference with cURL and fetch examples +- [Payment Bridging](./payment-bridging.md) - Cross-chain payment logic and receiving addresses +- [Data Types](./types.md) - Interface definitions and data structures + +## Quick Start + +### cURL Example + +```bash +curl -X POST https://intentapi.rozo.ai/payment-api \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -d '{ + "appId": "your-app-id", + "display": { + "intent": "Purchase item", + "paymentValue": "1", + "currency": "USD" + }, + "destination": { + "chainId": "8453", + "amountUnits": "1", + "tokenSymbol": "USDC" + } + }' +``` + +### JavaScript Fetch + +```javascript +const response = await fetch("https://intentapi.rozo.ai/payment-api", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_API_KEY", + }, + body: JSON.stringify({ + appId: "your-app-id", + display: { + intent: "Purchase item", + paymentValue: "1", + currency: "USD", + }, + destination: { + chainId: "8453", + amountUnits: "1", + tokenSymbol: "USDC", + }, + }), +}); + +const payment = await response.json(); +``` + +## Authentication + +Include API credentials in request headers as configured in your application: + +```bash +Authorization: Bearer YOUR_API_KEY +``` + +## Support + +For questions about the Rozo Payment API, contact the development team or refer to the main documentation. diff --git a/intent-pay/API/endpoints.md b/intent-pay/API/endpoints.md new file mode 100644 index 0000000..ee50fa2 --- /dev/null +++ b/intent-pay/API/endpoints.md @@ -0,0 +1,148 @@ +# API Endpoints + +Base URL: `https://intentapi.rozo.ai` + +## Create Payment + +`POST /payment-api` + +Creates a new payment request. + +**Request Body:** `PaymentRequestData` +**Response:** `PaymentResponseData` + +### cURL Example + +```bash +curl -X POST https://intentapi.rozo.ai/payment-api \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -d '{ + "appId": "your-app-id", + "display": { + "intent": "Premium subscription", + "paymentValue": "29.99", + "currency": "USD" + }, + "destination": { + "chainId": "8453", + "amountUnits": "29.99", + "tokenSymbol": "USDC" + }, + "externalId": "sub_12345", + "metadata": { + "userId": "user_67890" + } + }' +``` + +### JavaScript Fetch + +```javascript +const response = await fetch("https://intentapi.rozo.ai/payment-api", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_API_KEY", + }, + body: JSON.stringify({ + appId: "your-app-id", + display: { + intent: "Premium subscription", + paymentValue: "29.99", + currency: "USD", + }, + destination: { + chainId: "8453", + amountUnits: "29.99", + tokenSymbol: "USDC", + }, + }), +}); + +const payment = await response.json(); + +// Example response: +/* +{ + "id": "2a41baa0-c2b8-4360-af5a-eda0fef3e914", + "status": "payment_unpaid", + "createdAt": "2025-09-21T15:29:29.857+00:00", + "display": { + "intent": "Pay", + "currency": "USDC" + }, + "source": null, + "destination": { + "destinationAddress": "GAA3PV4SN4AEFGYXTHLO7X4ETQEM6PERUJN2NGRGMKEHNJSYYTIFMM5S", + "txHash": null, + "chainId": "1500", + "amountUnits": "0.1", + "tokenSymbol": "USDC", + "tokenAddress": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN" + }, + "metadata": { + "receivingAddress": "0x13735745e512befb599ab1bf44021290cab148c9", + "payinchainid": "137", + "payintokenaddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", + "webhookUrl": "https://example.com/webhook" + }, + "url": "http://checkout.example.com/pay?id=2a41baa0-c2b8-4360-af5a-eda0fef3e914" +} +*/ +``` + +## Get Payment by ID + +`GET /payment-api/id/{paymentId}` + +Retrieves payment by Rozo payment ID. + +**Parameters:** + +- `paymentId` (string): Payment ID + +**Response:** `PaymentResponseData` + +### cURL Example + +```bash +curl -X GET https://intentapi.rozo.ai/payment-api/id/pay_abc123 \ + -H "Authorization: Bearer YOUR_API_KEY" +``` + +### JavaScript Fetch + +```javascript +const response = await fetch( + "https://intentapi.rozo.ai/payment-api/id/pay_abc123", + { + headers: { + Authorization: "Bearer YOUR_API_KEY", + }, + } +); + +const payment = await response.json(); +``` + +## HTTP Status Codes + +| Code | Description | +| ---- | --------------------------------- | +| 200 | Success | +| 400 | Bad Request - Invalid data | +| 401 | Unauthorized - Invalid auth | +| 404 | Not Found - Payment doesn't exist | +| 429 | Too Many Requests - Rate limited | +| 500 | Internal Server Error | + +## Error Response Format + +```typescript +{ + data: null, + error: Error, + status: 400 +} +``` diff --git a/intent-pay/API/payment-bridging.md b/intent-pay/API/payment-bridging.md new file mode 100644 index 0000000..a062fee --- /dev/null +++ b/intent-pay/API/payment-bridging.md @@ -0,0 +1,333 @@ +# Payment Routing Logic + +This document explains how payment routing works when users want to pay out to different chains and tokens, particularly USDC on Stellar or Base networks. + +## Overview + +The payment system supports cross-chain payments where users can: + +- **Pay In** from one chain/token (Polygon USDC, Solana USDC, Stellar USDC, BSC USDT) +- **Pay Out** to a different chain/token (Base USDC, Stellar USDC, Solana USDC) + +## Key Concept: receivingAddress + +When creating a payment, the API returns a `receivingAddress` in the response metadata. This address becomes the **final destination** where funds should be sent, overriding the original destination address. + +```javascript +// After creating payment +const response = await fetch("https://intentapi.rozo.ai/payment-api", { + /* ... */ +}); +const payment = await response.json(); + +// Example response structure: +/* +{ + "id": "2a41baa0-c2b8-4360-af5a-eda0fef3e914", + "status": "payment_unpaid", + "destination": { + "destinationAddress": "GAA3PV4SN4AEFGYXTHLO7X4ETQEM6PERUJN2NGRGMKEHNJSYYTIFMM5S", + "chainId": "1500" + }, + "metadata": { + "receivingAddress": "0x13735745e512befb599ab1bf44021290cab148c9", + "payinchainid": "137", + "payintokenaddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359" + }, + "url": "http://checkout.example.com/pay?id=2a41baa0-c2b8-4360-af5a-eda0fef3e914" +} +*/ + +// IMPORTANT: Always use receivingAddress as the final destination +const finalDestination = payment.metadata.receivingAddress; +const checkoutUrl = payment.url; + +// Check if memo is required (for Stellar and Solana payments) +const memoRequired = payment.metadata.memo !== null; +const memo = payment.metadata.memo; +``` + +## Supported Payment Routes + +### Pay Out to Base USDC + +```javascript +const paymentData = { + appId: "your-app-id", + display: { + intent: "Cross-chain payment", + paymentValue: "100.00", + currency: "USD", + }, + destination: { + destinationAddress: "0x1234...", // Base address + chainId: "8453", // Base chain ID + amountUnits: "100000000", // $100 in USDC units (6 decimals) + tokenSymbol: "USDC", + tokenAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC + }, + preferredChain: "base", + preferredToken: "USDC", +}; +``` + +### Pay Out to Stellar USDC + +```javascript +const paymentData = { + appId: "your-app-id", + display: { + intent: "Payment to Stellar", + paymentValue: "100.00", + currency: "USD", + }, + destination: { + destinationAddress: "GCKFBEIYTKP...", // Stellar address + chainId: "stellar-mainnet", // Stellar chain ID + amountUnits: "100000000", + tokenSymbol: "USDC", + tokenAddress: + "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN", // Stellar USDC asset + }, + preferredChain: "stellar", + preferredToken: "USDC", +}; +``` + + + +## Pay In Options + +Users can pay from different chains while paying out to their preferred destination: + +### Pay In from Polygon USDC + +```javascript +const paymentData = { + // ... destination stays the same + preferredChain: "137", // Polygon chain ID + preferredToken: "USDC", + preferredTokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // Polygon USDC +}; +``` + +### Pay In from Stellar USDC (Memo Required) + +When users pay in from Stellar, a memo is **required** for the payment transaction. + +```javascript +const paymentData = { + // ... destination stays the same + preferredChain: "1500", // Stellar chain ID + preferredToken: "USDC", + // No preferredTokenAddress needed for Stellar +}; + +// After creating the payment, check for memo requirement +const payment = await createPayment(paymentData); + +if (payment.metadata.memo) { + console.log("MEMO REQUIRED for Stellar payment:", payment.metadata.memo); + // User MUST include this memo when sending Stellar USDC +} +``` + +### Pay In from Solana USDC (Memo Required) + +When users pay in from Solana, a memo is **required** for the payment transaction. + +```javascript +const paymentData = { + // ... destination stays the same + preferredChain: "900", // Solana chain ID + preferredToken: "USDC", + preferredTokenAddress: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // Solana USDC +}; + +// After creating the payment, check for memo requirement +const payment = await createPayment(paymentData); + +if (payment.metadata.memo) { + console.log("MEMO REQUIRED for Solana payment:", payment.metadata.memo); + // User MUST include this memo when sending Solana USDC +} +``` + +### Pay In from BSC USDT + +```javascript +const paymentData = { + // ... destination stays the same + preferredChain: "56", // BSC chain ID + preferredToken: "USDT", + preferredTokenAddress: "0x55d398326f99059fF775485246999027B3197955", // BSC USDT +}; +``` + +## Complete Example: Cross-Chain Payment + +```javascript +async function createCrossChainPayment() { + // User wants to pay out to Stellar USDC, but pay in from Polygon + const paymentRequest = { + appId: "my-app", + display: { + intent: "Cross-chain payment to Stellar", + paymentValue: "250.00", + currency: "USD", + }, + // Pay OUT to Stellar + destination: { + destinationAddress: + "GCKFBEIYTKP7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5", + chainId: "stellar-mainnet", + amountUnits: "250000000", // $250 USDC + tokenSymbol: "USDC", + tokenAddress: + "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN", + }, + // Pay IN from Polygon + preferredChain: "137", + preferredToken: "USDC", + preferredTokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", + externalId: "payment_123", + metadata: { + userId: "user_456", + description: "Cross-chain USDC transfer", + }, + }; + + try { + const response = await fetch("https://intentapi.rozo.ai/payment-api", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_API_KEY", + }, + body: JSON.stringify(paymentRequest), + }); + + const payment = await response.json(); + + // IMPORTANT: Always use receivingAddress from response + const finalDestination = payment.metadata.receivingAddress; + const checkoutUrl = payment.url; + + console.log( + "Original destination:", + paymentRequest.destination.destinationAddress + ); + console.log("Final receiving address:", finalDestination); + console.log("Payment ID:", payment.id); + console.log("Checkout URL:", checkoutUrl); + + return { + paymentId: payment.id, + finalDestination, + checkoutUrl, + status: payment.status, + payInChain: payment.metadata.payinchainid, + payInToken: payment.metadata.payintokenaddress, + memo: payment.metadata.memo, // Required for Stellar/Solana + memoRequired: payment.metadata.memo !== null, + }; + } catch (error) { + console.error("Payment creation failed:", error); + throw error; + } +} +``` + +## Chain and Token Reference + +### Supported Chains + +| Chain | Chain ID | Description | +| ------- | ---------------- | ------------------- | +| Base | `8453` | Base mainnet | +| Polygon | `137` | Polygon mainnet | +| BSC | `56` | Binance Smart Chain | +| Stellar | `1500` | Stellar network | +| Solana | `solana-mainnet` | Solana network | + +### Token Addresses + +#### USDC Addresses + +- **Base**: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` +- **Polygon**: `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` +- **Stellar**: `USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN` +- **Solana**: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` + +#### USDT Addresses + +- **BSC**: `0x55d398326f99059fF775485246999027B3197955` + +## Error Handling + +```javascript +async function createPaymentWithErrorHandling(paymentData) { + try { + const payment = await createRozoPayment(paymentData); + + if (!payment.data?.id) { + throw new Error(payment.error?.message || "Payment creation failed"); + } + + // Extract receiving address if provided + const receivingAddress = payment.data.metadata?.receivingAddress; + + return { + success: true, + paymentId: payment.data.id, + receivingAddress: + receivingAddress || paymentData.destination.destinationAddress, + originalDestination: paymentData.destination.destinationAddress, + }; + } catch (error) { + console.error("Payment creation error:", error); + return { + success: false, + error: error.message, + }; + } +} +``` + +## Best Practices + +1. **Always check for receivingAddress** in the API response +2. **Check for memo requirements** - required for Stellar and Solana payments +3. **Store both original and final destinations** for tracking +4. **Use external IDs** to correlate payments with your system +5. **Include comprehensive metadata** for better tracking +6. **Handle cross-chain delays** - payments may take time to process +7. **Validate chain IDs and token addresses** before sending +8. **Monitor payment status** using the GET endpoint + +## Payment Status Flow + +1. **payment_unpaid** - Payment created, awaiting user payment +2. **payment_progress** - Cross-chain bridge in progress +3. **payment_completed** - Funds delivered to final destination +4. **payment_expired** - Payment expired diff --git a/intent-pay/API/types.md b/intent-pay/API/types.md new file mode 100644 index 0000000..cbd661c --- /dev/null +++ b/intent-pay/API/types.md @@ -0,0 +1,156 @@ +# Data Types & Schemas + +## Core Interfaces + +### PaymentDisplay + +Display information for user interfaces. + +```typescript +interface PaymentDisplay { + intent: string; // Payment description/purpose + paymentValue: string; // Human-readable amount (e.g., "29.99") + currency: string; // Currency code (USD, EUR, etc.) +} +``` + +### PaymentDestination + +Where the payment should be sent. + +```typescript +interface PaymentDestination { + destinationAddress?: string; // Recipient wallet address + chainId: string; // Blockchain network ID + amountUnits: string; // Amount in smallest token units + tokenSymbol: string; // Token symbol (USDC, ETH, etc.) + tokenAddress?: string; // Token contract address + txHash?: string | null; // Transaction hash (set after payment) +} +``` + +### PaymentSource + +Payment source information. + +```typescript +interface PaymentSource { + sourceAddress?: string; // Sender wallet address + [key: string]: unknown; // Additional metadata +} +``` + +### PaymentRequestData + +Data required to create a payment. + +```typescript +interface PaymentRequestData { + appId: string; // Your application ID + display: PaymentDisplay; // Display information + destination: PaymentDestination; // Payment destination + externalId?: string; // Your internal reference ID + metadata?: Record; // Additional metadata + preferredChain?: string; // Preferred blockchain + preferredToken?: string; // Preferred token symbol + preferredTokenAddress?: string; // Preferred token address + [key: string]: unknown; // Extensible for future fields +} +``` + +### PaymentResponseData + +Complete payment information from API. + +```typescript +interface PaymentResponseData { + id: string; // Unique payment ID + status: string; // Payment status (e.g., "payment_unpaid") + createdAt: string; // ISO timestamp + display: { + intent: string; // Payment intent + currency: string; // Currency (e.g., "USDC") + }; + source: PaymentSource | null; // Source information (null initially) + destination: { + destinationAddress: string; // Recipient address + txHash: string | null; // Transaction hash (null initially) + chainId: string; // Chain ID (e.g., "1500" for Stellar) + amountUnits: string; // Amount in token units + tokenSymbol: string; // Token symbol + tokenAddress: string; // Token contract/asset address + }; + metadata: { + receivingAddress?: string; // IMPORTANT: Final receiving address + payinchainid?: string; // Pay-in chain ID + payintokenaddress?: string; // Pay-in token address + memo?: string | null; // REQUIRED memo for Stellar and Solana payments + webhookUrl?: string; // Webhook URL for notifications + [key: string]: unknown; // Additional metadata + }; + url: string; // Checkout URL for payment +} +``` + +### ApiResponse + +Standard API response wrapper. + +```typescript +interface ApiResponse { + data: T | null; // Response data + error: Error | null; // Error information + status: number | null; // HTTP status code +} +``` + +### RequestState + +Hook state for React components. + +```typescript +interface RequestState { + data: T | null; // Response data + error: Error | null; // Error information + status: number | null; // HTTP status + isLoading: boolean; // Loading state + isError: boolean; // Error state + isSuccess: boolean; // Success state +} +``` + +## Payment Status Values + +| Status | Description | +| ---------------- | ------------------------------ | +| `payment_unpaid` | Payment created, awaiting user | +| `processing` | Payment being processed | +| `completed` | Payment successful | +| `failed` | Payment failed | +| `cancelled` | Payment cancelled | +| `expired` | Payment expired | + +## Chain IDs + +Common blockchain network identifiers: + +| Chain | ID | Name | +| ------- | ------ | ------------------- | +| Base | `8453` | Mainnet | +| Polygon | `137` | Polygon | +| BSC | `56` | Binance Smart Chain | +| Stellar | `1500` | Stellar Mainnet | +| Solana | `900` | Solana Mainnet | + +## Token Addresses + +### USDC Addresses + +- Base: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` +- Polygon: `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` +- Stellar: `USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN` +- Solana: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` + +### USDT Address + +- BSC: `0x55d398326f99059fF775485246999027B3197955` diff --git a/intent-pay/ai-prompts.md b/intent-pay/ai-prompts.md index 686a939..63e8621 100644 --- a/intent-pay/ai-prompts.md +++ b/intent-pay/ai-prompts.md @@ -4,8 +4,30 @@ Use this prompt with any AI service to generate a complete RozoAI Intent Pay implementation: -``` -Create a React component with RozoAI Intent Pay SDK for crypto payments. Use demo app ID "rozoDemo" for testing, accept Base USDC payments (chain ID 8453), and include all required providers (WagmiProvider, QueryClientProvider, RozoPayProvider) in proper nesting order. IMPORTANT: Use getDefaultConfig from @rozoai/intent-pay (NOT createConfig from wagmi) to create the wagmiConfig. Add payment event handlers (onPaymentStarted, onPaymentCompleted, onPaymentBounced) with console logging and user-friendly alerts. Use TypeScript with proper types, include form validation if creating input fields, and ensure mobile-responsive design with TailwindCSS. Import baseUSDC from @rozoai/intent-common and wrap addresses with getAddress() from viem. Refer to this Guide Docs: https://docs.rozo.ai/intent-pay/quick-start.md +```text +Create a React component with RozoAI Intent Pay SDK for crypto payments. +Use demo app ID "rozoDemo" for testing, accept Base USDC payments +(chain ID 8453), and include all required providers +(WagmiProvider, QueryClientProvider, RozoPayProvider) +in proper nesting order. + +IMPORTANT: +- Use getDefaultConfig from @rozoai/intent-pay + (NOT createConfig from wagmi) to create the wagmiConfig. +- Ensure the code imports packages from the latest SDK release, not from + deprecated or older versions. Use @rozoai/intent-pay@latest and @rozoai/intent-common@latest + +Add payment event handlers (onPaymentStarted, onPaymentCompleted, +onPaymentBounced) with console logging and user-friendly alerts. + +Use TypeScript with proper types, include form validation if creating +input fields, and ensure mobile-responsive design with TailwindCSS. + +Import baseUSDC from @rozoai/intent-common and wrap addresses +with getAddress() from viem. + +Refer to this Guide Docs: +https://docs.rozo.ai/intent-pay/quick-start.md ``` ## ๐Ÿš€ One-Click Generation diff --git a/intent-pay/quick-start.md b/intent-pay/quick-start.md index b46b263..02d677d 100644 --- a/intent-pay/quick-start.md +++ b/intent-pay/quick-start.md @@ -5,7 +5,7 @@ Get up and running with RozoAI Intent Pay SDK in 5 minutes. ## ๐Ÿš€ Installation ```bash -npm install @rozoai/intent-pay @rozoai/intent-common @tanstack/react-query wagmi viem +npm install @rozoai/intent-pay@latest @rozoai/intent-common@latest @tanstack/react-query wagmi viem ``` ## ๐Ÿ“ Basic Setup diff --git a/intent-pay/troubleshooting.md b/intent-pay/troubleshooting.md index 13826d9..ac6454a 100644 --- a/intent-pay/troubleshooting.md +++ b/intent-pay/troubleshooting.md @@ -111,7 +111,7 @@ If you're still experiencing issues: - ๐Ÿ› **GitHub Issues**: [GitHub Issues](https://github.com/rozoai/intent-pay/issues) 3. **Direct Support:** - - ๐Ÿ“ง **Email**: support@rozo.ai + - ๐Ÿ“ง **Email**: When reporting issues, please include: