feat: add Intent API Docs

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)

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.

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
+}
+```