{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Build with AI","description":"Vibe code resources for the Trustap API","llmstxt":{"hide":false,"title":"Trustap API","description":"Trustap is an API for end-to-end transaction solution that seamlessly integrates payments, fulfillment, and support into your marketplace. Trustap is an escrow API service facilitating secure transactions.","sections":[{"title":"Intro","description":"Trustap API introduction.","includeFiles":["docs/intro/*.md"],"excludeFiles":[]},{"title":"Concepts","description":"Trustap Concepts","includeFiles":["docs/concepts/*.md"],"excludeFiles":["docs/concepts/errors.md"]},{"title":"Guides","description":"Trustap integration guides","includeFiles":["docs/guides/**/*.md"],"excludeFiles":["docs/guides/listing/"]},{"title":"API Reference","description":"Trustap API reference guide","includeFiles":["**/apis/openapi.yaml"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"create-an-app-with-ai","__idx":0},"children":["Create an app with AI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Trustap supports AI-assisted API integrations using structured documentation, predefined rules, and reusable integration assets."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To build an application with AI, follow these steps."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provide your AI tool with Trustap guardrails."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Supply structured integration resources."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use a guided prompt to generate the application."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-guardrails","__idx":2},"children":["1. Guardrails"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Guardrails define how an AI should interact with the Trustap API."," ","Provide the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://trustap-docs--tpd-366-review-vibe-code-options-f-dc435d.preview.redocly.app/AI/trustap-ai-rules.ts"},"children":["Trustap guardrail rule file"]}," to your AI to describe how to work with the Trustap API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-integration-resources","__idx":3},"children":["2. Integration resources"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These files provide structured context for generating a working integration. Provide these files to your AI tool alongside the guardrails for a Trustap API online flow."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"File"},"children":["File"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://trustap-docs--tpd-366-review-vibe-code-options-f-dc435d.preview.redocly.app/AI/trustap-endpoints.ts"},"children":["trustap-endpoints.ts"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API surface and request definitions"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://trustap-docs--tpd-366-review-vibe-code-options-f-dc435d.preview.redocly.app/AI/trustap-integration-cookbook.ts"},"children":["trustap-integration-cookbook.ts"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Implementation pattern for online transaction"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://trustap-docs--tpd-366-review-vibe-code-options-f-dc435d.preview.redocly.app/AI/trustap-oauth.ts"},"children":["trustap-oauth.ts"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OAuth flow handling"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://trustap-docs--tpd-366-review-vibe-code-options-f-dc435d.preview.redocly.app/AI/trustap-online-cc-workflow.ts"},"children":["trustap-online-cc-workflow.ts"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Card payment transaction flow"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://trustap-docs--tpd-366-review-vibe-code-options-f-dc435d.preview.redocly.app/AI/trustap-state-machine.ts"},"children":["trustap-state-machine.ts"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction lifecycle and states"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://trustap-docs--tpd-366-review-vibe-code-options-f-dc435d.preview.redocly.app/AI/trustap-ui.ts"},"children":["trustap-ui.ts"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UI behaviour and interaction patterns"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-guided-prompt-build-with-lovable","__idx":4},"children":["3. Guided prompt: Build with Lovable"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://lovable.ai"},"children":["Lovable.ai"]}," generates a full-stack application from structured prompts and supporting files."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pre-built-prompts","__idx":5},"children":["Pre-built prompts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the following pre-build prompts as a template to add Trustap to your AI-assisted project."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"create-a-application-that-implements-a-trustap-online-flow-using-card-payments","__idx":6},"children":["Create a application that implements a Trustap online flow using card payments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The prompt creates a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://trustap-docs--tpd-366-review-vibe-code-options-f-dc435d.preview.redocly.app/AI/lovable-sample-prompt.md"},"children":["peer-to-peer marketplace"]},". Sellers post items to sell. Buyers select on-sale items and pay for them using Trustap. Sellers accept payment, and add shipping tracking details. Finally, sellers confirm delivery and retrieve the money from the transaction to receive a payout."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"# Vault P2P — Complete Build Prompt\n\n## Overview\n\nBuild a **P2P escrow marketplace** called **\"Vault P2P\"** where users can list items for sale, and buyers can purchase them through **Trustap escrow** (credit card payments with hosted payment pages). The app uses **EUR (€)** as its default currency. All monetary values are stored as **integers in cents**.\n\nNo user authentication — this is a public prototype. All database tables have open RLS policies.\n\n---\n\n## Tech Stack\n\n- React + TypeScript + Vite\n- Tailwind CSS with shadcn/ui components\n- Lovable Cloud (Supabase) for database + edge functions\n- Trustap API for escrow transactions\n- React Router for navigation\n- TanStack React Query\n\n---\n\n## Design System\n\n### Font\nImport **Geist Mono** from Google Fonts for monospaced elements (prices, transaction IDs). Body uses system font stack (`Geist Sans, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif`).\n\n### CSS Variables (index.css)\nLight mode:\n```\n--background: 0 0% 100%\n--foreground: 222 47% 11%\n--primary: 221 83% 53%\n--primary-foreground: 210 40% 98%\n--secondary: 210 40% 96%\n--muted: 210 40% 96%\n--muted-foreground: 215 16% 47%\n--border: 214 32% 91%\n--ring: 221 83% 53%\n--success: 160 84% 39%\n--warning: 38 92% 50%\n--bg-subtle: 210 40% 98%\n--radius: 0.75rem\n```\n\nDark mode (`.dark` class):\n```\n--background: 222 47% 6%\n--foreground: 210 40% 98%\n--primary: 217 91% 60%\n--border: 217 33% 17%\n--muted: 217 33% 17%\n--muted-foreground: 215 20% 65%\n--bg-subtle: 222 47% 8%\n```\n\n### Custom Button Variant\nAdd a `trustap` variant to the Button component:\n```\ntrustap: \"bg-primary text-primary-foreground hover:bg-primary/90 shadow-md font-semibold\"\n```\n\n### Custom Badge Variants\nAdd status badge variants: `pending`, `paid`, `in_transit`, `settled` — using muted yellows, greens, blues, and emeralds.\n\n### Animations\nAdd a `fade-in` keyframe animation:\n```\nfrom: { opacity: \"0\", transform: \"translateY(8px)\" }\nto: { opacity: \"1\", transform: \"translateY(0)\" }\n```\nDuration: `0.4s cubic-bezier(0.16, 1, 0.3, 1)`\n\n---\n\n## Routes\n\n| Path | Component | Description |\n|------|-----------|-------------|\n| `/` | Index | Homepage with listing grid |\n| `/sell` | CreateListing | Form to create a new listing |\n| `/checkout/:id` | Checkout | Two-step checkout (info → review + pay) |\n| `/dashboard` | Dashboard | Seller transaction management |\n| `/oauth/callback` | OAuthCallback | Handles Trustap OAuth redirect |\n\n---\n\n## Database Schema\n\n### Table: `listings`\n| Column | Type | Default | Notes |\n|--------|------|---------|-------|\n| id | uuid | gen_random_uuid() | PK |\n| title | text | — | required |\n| price_cents | integer | — | required, in cents |\n| image_url | text | unsplash placeholder URL | |\n| seller_email | text | — | required |\n| seller_name | text | — | required |\n| trustap_seller_id | text | null | filled after guest user creation |\n| created_at | timestamptz | now() | |\n\n**RLS**: Public read + insert (no auth).\n\n### Table: `transactions`\n| Column | Type | Default | Notes |\n|--------|------|---------|-------|\n| id | uuid | gen_random_uuid() | PK |\n| listing_id | uuid | — | FK → listings.id |\n| trustap_transaction_id | integer | null | from Trustap API |\n| amount_cents | integer | — | item price in cents |\n| fee_cents | integer | null | Trustap fee in cents |\n| charge_calculator_version | integer | null | from charge endpoint |\n| buyer_email | text | — | |\n| buyer_name | text | '' | |\n| seller_email | text | — | |\n| trustap_buyer_id | text | null | guest buyer ID (1-xxx) |\n| trustap_seller_id | text | null | guest seller ID (1-xxx), later replaced with full UUID |\n| tracking_carrier | text | null | |\n| tracking_code | text | null | |\n| payment_url | text | null | Trustap hosted payment URL |\n| status | text | 'pending' | see status values below |\n| created_at | timestamptz | now() | |\n| updated_at | timestamptz | now() | |\n\n**RLS**: Public read + insert + update (no auth, no delete).\n\n**Enable realtime** on the `transactions` table:\n```sql\nALTER PUBLICATION supabase_realtime ADD TABLE public.transactions;\n```\n\n### Transaction Status Values\n`pending` → `joined` → `paid` → `tracked` → `delivered` → `complaint` / `complaint_period` → `resolved` → `funds_released` / `settled`\n\n---\n\n## Utility Library: `src/lib/marketplace.ts`\n\n```typescript\n// Format cents to display string\nformatCents(cents: number, currency = \"eur\"): string\n// Symbols: { eur: \"€\", usd: \"$\", gbp: \"£\" }\n\n// Convert decimal string to cents\ndollarsToCents(dollars: string): number\n\n// Types\ntype TransactionStatus = \"pending\" | \"joined\" | \"paid\" | \"tracked\" | \"delivered\" | \"complaint\" | \"complaint_period\" | \"resolved\" | \"funds_released\" | \"settled\"\n\ninterface Listing { id, title, price_cents, image_url, seller_email, seller_name, created_at, trustap_seller_id? }\ninterface Transaction { id, listing_id, trustap_transaction_id?, buyer_email, seller_email, trustap_buyer_id?, trustap_seller_id?, amount_cents, fee_cents?, status, tracking_carrier?, tracking_code?, created_at }\n\n// Status badge variant mapper\ngetStatusBadgeVariant(status): \"pending\" | \"paid\" | \"in_transit\" | \"settled\"\n\n// Human-readable status labels\ngetStatusLabel(status): string\n// e.g. \"joined\" → \"Awaiting Payment\", \"paid\" → \"Funds in Escrow\", \"tracked\" → \"In Transit\"\n```\n\n---\n\n## Edge Function 1: `supabase/functions/trustap/index.ts`\n\n**Purpose**: Proxy all Trustap API calls through a single edge function.\n\n### Configuration\n- **Base URL**: `https://dev.stage.trustap.com/api/v1`\n- **Auth**: Basic Auth using `TRUSTAP_API_KEY` secret (username = API key, password = blank)\n  ```\n  Authorization: Basic ${btoa(apiKey + ':')}\n  ```\n- **CRITICAL**: Never use Bearer tokens for API requests. Only Basic Auth.\n\n### Actions (dispatched via `action` field in request body)\n\n#### `create_guest_user`\n```\nPOST /guest_users\nBody: { email, first_name, last_name, country_code, tos_acceptance: { unix_timestamp, ip } }\nReturns: { id: \"1-xxx-xxx-xxx\" } — guest user IDs always start with \"1-\"\n```\n\n#### `calculate_charge`\n```\nGET /charge?price={priceCents}&currency={currency}\nReturns: { charge, charge_calculator_version, ... }\n⚠️ MUST be called immediately before creating a transaction\n```\n\n#### `create_transaction`\n```\nPOST /me/transactions/create_with_guest_user\nHeader: Trustap-User: {seller_id}\nBody: { seller_id, buyer_id, price, charge, charge_calculator_version, currency, description, creator_role, image_url? }\nReturns: { id: 12345, status: \"joined\", ... }\n```\n\n#### `get_transaction`\n```\nGET /transactions/{transaction_id}\nReturns: full transaction object with current status\n```\n\n#### `add_tracking`\n```\nPOST /transactions/{transaction_id}/track_with_guest_seller\nHeader: Trustap-User: {seller_id}\nBody: { carrier, tracking_code }\n⚠️ Only call when status === \"paid\"\n```\n\n#### `confirm_delivery`\n```\nPOST /transactions/{transaction_id}/confirm_delivery_with_guest_buyer\nHeader: Trustap-User: {buyer_id}\nNo body required\n```\n\n#### `claim_for_seller`\n```\nPOST /transactions/{transaction_id}/claim_for_seller\nHeader: Trustap-User: {full_user_id}\n⚠️ full_user_id is a UUID from OAuth id_token \"sub\" claim — NOT the guest \"1-\" ID\n```\n\n### Error Handling\nAll Trustap API errors should be caught, logged with the URL and status code, and re-thrown as JSON error responses with status 500.\n\n---\n\n## Edge Function 2: `supabase/functions/trustap-oauth/index.ts`\n\n**Purpose**: Exchange OAuth authorization code for tokens and extract the permanent Trustap user ID.\n\n### Token Exchange\n```\nPOST https://sso.trustap.com/auth/realms/trustap-stage/protocol/openid-connect/token\nContent-Type: application/x-www-form-urlencoded  ⚠️ NOT JSON\n\nBody (URLSearchParams):\n  client_id: TRUSTAP_OAUTH_CLIENT_ID (from secrets)\n  client_secret: TRUSTAP_OAUTH_CLIENT_SECRET (from secrets)\n  grant_type: authorization_code\n  code: {authorization_code}\n  redirect_uri: {redirect_uri}\n```\n\n### Extract User ID\nDecode the `id_token` JWT (base64 decode the payload segment). The `sub` claim contains the permanent Trustap user ID (UUID format, no \"1-\" prefix).\n\nReturn: `{ trustap_user_id: \"<uuid>\" }`\n\n---\n\n## Required Secrets\n\nThese must be configured in the backend:\n1. `TRUSTAP_API_KEY` — Basic Auth username for all API calls\n2. `TRUSTAP_OAUTH_CLIENT_ID` — OAuth client ID for seller account upgrade\n3. `TRUSTAP_OAUTH_CLIENT_SECRET` — OAuth client secret for token exchange\n\n---\n\n## Frontend Client: `src/lib/trustap-client.ts`\n\n```typescript\n// Invoke the trustap edge function\ncallTrustap(action: string, params: Record<string, unknown>): Promise<any>\n\n// Same but returns { data, error } without throwing\ncallTrustapRaw(action: string, params: Record<string, unknown>)\n\n// Invoke the trustap-oauth edge function\nexchangeOAuthCode(code: string, redirectUri: string): Promise<{ trustap_user_id: string }>\n\n// Build Trustap hosted payment URL (browser redirect, NOT an API call)\ngetPaymentUrl(transactionId: number, redirectUri: string): string\n// → https://actions.stage.trustap.com/online/transactions/{id}/guest_pay?redirect_uri={uri}\n\n// Build OAuth authorization URL (browser redirect)\ngetOAuthUrl(clientId: string, redirectUri: string, state: string): string\n// → https://sso.trustap.com/auth/realms/trustap-stage/protocol/openid-connect/auth?client_id=...&redirect_uri=...&response_type=code&scope=openid basic_tx:offline_create_join basic_tx:offline_accept_payment basic_tx:offline_cancel basic_tx:offline_claim&state=...\n\n// Build profile completion URL\ngetProfileCompletionUrl(clientId: string, edit?: boolean): string\n// → https://app.stage.trustap.com/profile/payout/personal?edit=true&client_id=...\n```\n\n---\n\n## Page Details\n\n### Home (`/`)\n- Sticky header with Shield icon + \"Vault P2P\" brand, Dashboard link, \"Sell Item\" button (trustap variant)\n- Hero section: \"Secure P2P Transactions.\" heading, subtitle about Trustap escrow\n- Grid of listing cards (1-3 columns responsive) fetched from `listings` table\n- Each card shows image, title, seller name, price in €, \"Escrow Protected\" badge\n- Clicking a card navigates to `/checkout/{id}`\n- Empty state with \"Create Listing\" CTA\n\n### Create Listing (`/sell`)\n- Form fields: Item Title, Price (EUR) with € prefix, Image URL (optional), Your Name, Your Email\n- Inserts into `listings` table\n- Redirects to `/` on success\n\n### Checkout (`/checkout/:id`)\nTwo-step flow:\n\n**Step 1 — Info**: Buyer enters name + email → calls `calculate_charge` → shows fee breakdown\n**Step 2 — Review**: Shows item price, Trustap fee, total → \"Pay with Trustap\" button\n\nOn submit:\n1. Create guest seller (using listing's seller info + country_code \"ie\" + tos_acceptance)\n2. Create guest buyer (using buyer info + country_code \"ie\" + tos_acceptance)\n3. Create transaction via `create_transaction` with `creator_role: \"seller\"`\n4. Build payment URL with `redirect_uri` = `window.location.origin` (home page)\n5. Insert transaction record into database with status \"joined\"\n6. Redirect buyer to Trustap hosted payment page (`window.location.href = paymentUrl`)\n\nThe `tos_acceptance` object: `{ unix_timestamp: Math.floor(Date.now() / 1000), ip: \"127.0.0.1\" }`\n\n### Dashboard (`/dashboard`)\n- Lists all transactions with listing info, status badges, amounts, fees, buyer email\n- Realtime subscription on `transactions` table for live updates\n- **Sync button**: Polls Trustap `get_transaction` to sync status\n- **Add Tracking** (when status === \"paid\"): Carrier + tracking code form → calls `add_tracking` → updates local DB to \"tracked\"\n- **Confirm Delivery** (when status === \"tracked\"): Calls `confirm_delivery` → updates to \"delivered\"\n- **Connect Bank** (when status === \"delivered\" or \"funds_released\" AND seller is guest \"1-\"): Redirects to Trustap OAuth SSO for account upgrade\n\nOAuth Client ID for bank connection: `5a3d7990-9f1c-4e11-8d67-3da5b160c50a`\nOAuth redirect URI: `${window.location.origin}/oauth/callback`\nState parameter: transaction's local DB `id`\n\n### OAuth Callback (`/oauth/callback`)\n1. Extract `code` and `state` (transaction ID) from URL params\n2. Call `exchangeOAuthCode(code, redirectUri)` to get `trustap_user_id`\n3. Look up `trustap_transaction_id` from transactions table using `state`\n4. Call `claim_for_seller` with the full Trustap user ID\n5. Update `trustap_seller_id` in local DB\n6. Show success toast + redirect to `/dashboard`\n\n---\n\n## Critical Trustap Integration Rules\n\n1. **Currency**: All amounts in integer cents. EUR is default.\n2. **Guest IDs**: Always prefixed with `1-`. Full user IDs are plain UUIDs.\n3. **Charge first**: Always call `calculate_charge` immediately before `create_transaction`.\n4. **Auth**: Basic Auth only (`API_KEY:` with blank password). Never Bearer tokens.\n5. **Trustap-User header**: Required on create_transaction (seller ID), add_tracking (seller ID), confirm_delivery (buyer ID), claim_for_seller (full UUID).\n6. **Hosted payment**: Buyers pay via redirect to Trustap's hosted page. Never simulate payments.\n7. **OAuth for payouts**: Guest sellers must OAuth-upgrade before receiving payouts. Use `sub` claim from `id_token`.\n8. **Never invent**: Don't invent API endpoints, transaction states, or bypass the payment page.\n9. **Redirect URIs**: Payment/action flows redirect to app root. OAuth flows redirect to `/oauth/callback`.\n\n---\n\n## Transaction Lifecycle State Machine\n\n```\njoined → paid → tracked → delivered → [complaint | complaint_period] → resolved → funds_released\n```\n\n- `joined`: Transaction created, awaiting buyer payment\n- `paid`: Buyer paid via hosted page, funds in escrow\n- `tracked`: Seller added shipping tracking\n- `delivered`: Buyer confirmed receipt\n- `complaint`: Buyer filed complaint (pauses payout)\n- `funds_released`: Payout to seller complete\n\n---\n\n## Zod Validation Schemas\n\nCreate `src/lib/trustap-endpoints.ts` with Zod schemas for all Trustap API request/response types plus URL builder helper functions:\n\n- `CreateGuestUserRequest/Response` — validates email, name, country_code (2-char), tos_acceptance object\n- `CalculateChargeRequest/Response` — price (positive int), currency enum (gbp/eur/usd)\n- `CreateTransactionRequest` — seller_id (1-xxx), buyer_id (1-xxx), creator_role, price, charge, charge_calculator_version\n- `GuestPayRedirect` + `buildGuestPayUrl()` — transaction_id + redirect_uri\n- `SSOAuthRedirect` + `buildSSOAuthUrl()` — client_id, redirect_uri, response_type, scope, state\n- `SSOTokenExchangeRequest/Response` — includes id_token JWT\n- `DecodedIdToken` — sub (UUID), email, preferred_username\n- `ProfileCompletionRedirect` + `buildProfileCompletionUrl()` — client_id, edit\n- `ClaimForSellerParams` — transaction_id + trustap_user_id (full UUID)\n- `TransactionResponse` — comprehensive schema with all status fields, tracking details, timestamps\n\nCarrier enum: `ups | dhl | fedex | an_post | royal_mail`\nCurrency enum: `gbp | eur | usd`\n\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"add-trustap-as-a-payment-method-for-existing-lovable-built-marketplace","__idx":7},"children":["Add Trustap as a payment method for existing Lovable built marketplace"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The prompt takes a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://trustap-docs--tpd-366-review-vibe-code-options-f-dc435d.preview.redocly.app/AI/lovable-integrate-existing-marketplace.md"},"children":["marketplace"]}," that you have already built using Lovable and adds Trustap as an escrow-like payment option."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"# Add Trustap as payment processor to existing build prompt\n\n## Overview\nAdd **Trustap** as the payment processor for this marketplace project. Use the attached support files as the authoritative source for all Trustap API logic:\n\n1. `trustap-ai-rules.ts` – forbidden actions, auth rules, fee/transaction hints, guardrails.\n2. `trustap-endpoints.ts` – all permitted endpoints (methods, URLs, headers, payloads).\n3. `trustap-online-cc-workflow.ts` – ordered workflow for the online credit-card flow.\n4. `trustap-base-urls.ts` – correct base URLs for stage/sandbox.\n\n## Scope & Environment\n- **Scope:** Full flow including OAuth seller account claim.\n- **Environment:** Stage / sandbox.\n- **Country:** Ireland (`ie`).\n- **Currency:** EUR.\n\n## Required Base URLs (stage)\n- API: `https://dev.stage.trustap.com/api/v1/`\n- Hosted actions (guest pay): `https://actions.stage.trustap.com`\n- SSO (OAuth): `https://sso.trustap.com/auth/realms/trustap-stage/protocol/openid-connect`\n\n## Secrets to request via the secrets tool\n- `TRUSTAP_API_KEY`\n- `TRUSTAP_OAUTH_CLIENT_ID`\n- `TRUSTAP_OAUTH_CLIENT_SECRET`\n\nDo **not** hardcode the OAuth client ID anywhere. Since secrets are not exposed to the frontend, create an edge function `trustap-oauth-config` that returns `client_id` to the browser, and have `SellerDashboard` fetch it before building the OAuth authorize URL.\n\n## Hard Rules\n- Only use endpoints defined in `trustap-endpoints.ts`. Never invent endpoints, states, or payment logic.\n- All Trustap API calls use **Basic Auth**: username = `TRUSTAP_API_KEY`, password = empty. (`Authorization: Basic base64(API_KEY:)`).\n- The `Trustap-User` header carries the guest id for guest-flow calls, and the **full Trustap user id** (JWT `sub`) for `claim_for_seller` — never mix them.\n- All prices sent to Trustap are **integers in cents**.\n- Poll transactions until status is `paid` before allowing the seller to add tracking; require `delivered`/buyer confirmation before completion.\n- OAuth token exchange uses `application/x-www-form-urlencoded`, not JSON.\n- Strip leading slashes from API paths so they resolve against the `/api/v1/` base.\n\n## Database (Supabase migrations)\n- `profiles`: add `trustap_guest_id text`, `trustap_user_id text`, `first_name`, `last_name`, `country_code` (default `ie`), `account_type` (`buyer` | `seller` | `admin`), `banned boolean`.\n- `listings`: ensure `status` supports `available`, `pending_approval`, `sold`; include `price numeric`, `currency text`, `image_url`, `seller_id`.\n- `transactions`: `listing_id`, `buyer_id`, `seller_id`, `price`, `currency`, `charge`, `status`, `trustap_transaction_id bigint unique`, `tracking_carrier`, `tracking_code`, timestamps.\n- RLS so buyers/sellers can only read their own transactions; admin role via separate `user_roles` table + `has_role()` security-definer function.\n\n## Edge Functions to create\nAll under `supabase/functions/`, sharing `_shared/trustap.ts` (basic-auth helper, `trustapFetch`, CORS, base URL constants):\n\n1. `trustap-create-transaction` – ensures guest users for buyer & seller (creating via `/guest_users` with `tos_acceptance` + IP if missing), calls `GET /charge`, then `POST /me/transactions/create_with_guest_user` with `Trustap-User: <sellerguestid>` and `creator_role: \"seller\"`. Inserts a `transactions` row, locks the listing to `pending_approval`, and returns `pay_url = {ACTIONS_BASE}/online/transactions/{id}/guest_pay?redirect_uri=...`.\n2. `trustap-poll-transaction` – `GET /transactions/{id}`, syncs status, marks listing `sold` on paid/tracked/delivered/funds_released, `available` on cancelled.\n3. `trustap-track` – verifies Trustap status is `paid`, then `POST /transactions/{id}/track_with_guest_seller` with seller guest id. Allowed carriers: `an_post`, `royal_mail`, `ups`, `dhl`, `fedex`.\n4. `trustap-confirm-delivery` – `POST /transactions/{id}/confirm_delivery_with_guest_buyer` with buyer guest id.\n5. `trustap-oauth-claim` – exchanges code at `{SSO_BASE}/token` (form-encoded), decodes `id_token`, saves `sub` to `profiles.trustap_user_id`, then optionally `POST /transactions/{id}/claim_for_seller` with `Trustap-User: <full trustap user id>`.\n6. `trustap-oauth-config` – returns `{ client_id: TRUSTAP_OAUTH_CLIENT_ID }` so the frontend can build the authorize URL without hardcoding.\n\nAdd detailed `console.error` logging in `trustapFetch` (status, method, path, response body) so 4xx/5xx responses are debuggable.\n\n## Frontend\n- `src/lib/trustap.ts` – currency helpers (symbol/format), carrier list, status label map.\n- `src/pages/Auth.tsx` – collect `first_name`, `last_name`, `country_code` (default `ie`) and `account_type` at signup; persist to `profiles`.\n- `src/pages/SellerDashboard.tsx` – list seller's listings/transactions; \"Connect Trustap account\" button that fetches `client_id` from `trustap-oauth-config` and redirects to the SSO authorize URL with `redirect_uri` pointing to `/seller/oauth/callback`; tracking form once a tx is `paid`.\n- `src/pages/SellerOAuthCallback.tsx` – reads `code`, calls `trustap-oauth-claim`.\n- `src/pages/BuyerDashboard.tsx` – buyer's transactions with poll + confirm-delivery buttons.\n- `src/pages/PaymentReturn.tsx` – landing page after hosted-pay redirect; polls until `paid`.\n- `ListingCard` / `ListingDetailModal` – \"Buy with Trustap\" button invoking `trustap-create-transaction` with `redirect_uri` = `/payment/return?tx=...`, then `window.location = pay_url`.\n- Register all new routes in `src/App.tsx`.\n\n## Auth\n- Standard email/password signup + login (no anonymous, no auto-confirm email unless asked).\n- Include Google OAuth provider.\n\nDeliver this end-to-end so a buyer can purchase a listing, the seller can claim via OAuth, add tracking once paid, and the buyer can confirm delivery — all against Trustap stage.\n\n\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"debugging","__idx":8},"children":["Debugging"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After you build something using vibe-coding, it may not work as expected. Use the following to help understand the issues and explain to our support team what has gone wrong."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"common-things-that-go-wrong","__idx":9},"children":["Common things that go wrong"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["It worked in Lovable / Cursor / ChatGPT's code but not in my app"]},"."," ","The AI may have written code that looks right but is missing a header, using the wrong method, or sending data in the wrong format. Try testing the same request in a tool like Postman or copy-paste your request details to us."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["I keep getting 401"]},"."," ","Your API key does not reach our server. Common causes: it's in the wrong place in your code, there's a typo, or it got accidentally hardcoded as a placeholder like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["API_KEY"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["The AI says my code is correct but it still fails"]},"."," ","AI coding tools are great at syntax but sometimes confuse our specific API rules. Share the code snippet and the error to help us identify issues."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-to-send-us-when-you-ask-for-help","__idx":10},"children":["What to send us when you ask for help"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the following pieces of information to our support team when looking for help."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The URL you were calling (e.g. https://api.stage.trustap.com/v1/orders)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The method (GET, POST, PUT, PATCH, DELETE)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The status code (the three-digit number)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The error message (the text that came back)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["What you were trying to do in plain English"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additionally, try to prove the following if you can."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your transaction ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A copy of what you sent (your request body — no real API keys or passwords)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"disclaimer","__idx":11},"children":["Disclaimer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Trustap provides AI tools to help with your integration. These tools are separate from our technical specifications. The written documentation is the only official guide for Trustap partners."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use AI responses as a starting point. Do not treat them as absolute facts. Trustap is not responsible for errors in AI content or for user mistakes. Use the verified documentation as the primary source for all API calls and workflows."]}]},"headings":[{"value":"Create an app with AI","id":"create-an-app-with-ai","depth":1},{"value":"How it works","id":"how-it-works","depth":2},{"value":"1. Guardrails","id":"1-guardrails","depth":2},{"value":"2. Integration resources","id":"2-integration-resources","depth":2},{"value":"3. Guided prompt: Build with Lovable","id":"3-guided-prompt-build-with-lovable","depth":2},{"value":"Pre-built prompts","id":"pre-built-prompts","depth":3},{"value":"Create a application that implements a Trustap online flow using card payments","id":"create-a-application-that-implements-a-trustap-online-flow-using-card-payments","depth":4},{"value":"Add Trustap as a payment method for existing Lovable built marketplace","id":"add-trustap-as-a-payment-method-for-existing-lovable-built-marketplace","depth":4},{"value":"Debugging","id":"debugging","depth":2},{"value":"Common things that go wrong","id":"common-things-that-go-wrong","depth":3},{"value":"What to send us when you ask for help","id":"what-to-send-us-when-you-ask-for-help","depth":3},{"value":"Disclaimer","id":"disclaimer","depth":2}],"frontmatter":{"seo":{"title":"Build with AI","description":"Vibe code resources for the Trustap API"}},"lastModified":"2026-06-08T08:43:23.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/intro/build-with-ai","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}