# Create an app with AI

Trustap supports AI-assisted API integrations using our [MCP](/docs/intro/mcp). Most AI applications can assess our documentation to guide your build.
In addition, we provide structured documentation, predefined rules, and reusable integration assets to more directly guide a vibe-coded experience.

## How it works

To build an application with AI, follow these steps.

1. Provide your AI tool with Trustap guardrails.
2. Supply structured integration resources.
3. Use a guided prompt to generate the application.


## 1. Guardrails

Guardrails define how an AI should interact with the Trustap API.
Provide the [Trustap guardrail rule file](https://docs.trustap.com/AI/v2-trustap-ai-rules.ts) to your AI to describe how to work with the Trustap API.

## 2. Integration resources

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.

| File | Description |
|  --- | --- |
| [trustap-endpoints.ts](https://docs.trustap.com/AI/v2-trustap-endpoints.ts) | API surface and request definitions |
| [trustap-integration-cookbook.ts](https://docs.trustap.com/AI/v2-trustap-integration-cookbook.ts) | Implementation pattern for online transaction |
| [trustap-oauth.ts](https://docs.trustap.com/AI/v2-trustap-oauth.ts) | OAuth flow handling |
| [trustap-online-cc-workflow.ts](https://docs.trustap.com/AI/v2-trustap-online-cc-workflow.ts) | Card payment transaction flow |
| [trustap-state-machine.ts](https://docs.trustap.com/AI/v2-trustap-state-machine.ts) | Transaction lifecycle and states |
| [trustap-ui.ts](https://docs.trustap.com/AI/v2-trustap-ui.ts) | UI behaviour and interaction patterns |
| [v2-types.d.ts](https://docs.trustap.com/AI/v2-types.d.ts) | Types file |


## 3. Guided prompt: Build with Lovable

[Lovable.ai](https://lovable.ai) generates a full-stack application from structured prompts and supporting files.

### Pre-built prompts

Use the following pre-build prompts as a template to add Trustap to your AI-assisted project.

#### Create a application that implements a Trustap online flow using card payments

The prompt creates a 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.

```markdown
# Vault P2P — Trustap v2 Integration Spec

## Overview

Vault P2P is a P2P escrow marketplace. Buyers purchase listed items through Trustap escrow (hosted card payments); sellers receive payout after an OAuth account upgrade. All monetary values are integers in cents. Currency is EUR only.

## Tech Stack

- React + TypeScript + Vite
- TanStack Start — server functions handle the Trustap proxy and OAuth exchange, not Supabase Edge Functions
- Tailwind CSS + shadcn/ui
- Supabase (Lovable Cloud) for `listings` and `transactions` tables, with realtime enabled on `transactions`
- TanStack React Query

## Routes

| Path | Purpose |
|---|---|
| `/` | Listing grid |
| `/sell` | Create a listing |
| `/checkout/:id` | Two-step escrow checkout |
| `/payment/complete` | Trustap post-payment redirect target |
| `/dashboard` | Transaction management: sync, accept payment, tracking, OAuth claim |
| `/oauth/callback` | OAuth code exchange and transaction claim |

## Trustap API Rules

**Base URL:** `https://api.test.trustap.com/v2` (staging only — no production URL configured).

**Authentication:** Basic Auth on every call — `Authorization: Basic <base64(API_KEY:)>`, username is the API key, password blank. Never Bearer tokens for direct API calls.

**Secrets (server-side only, never exposed to the browser):**
- `TRUSTAP_API_KEY`
- `TRUSTAP_OAUTH_CLIENT_ID`
- `TRUSTAP_OAUTH_CLIENT_SECRET`

**OAuth scope:** `openid` only.

**`Trustap-User` header:** required on actor-specific action endpoints — `accept_payment`, `track`, `confirm_delivery`, `claim` — set to the acting user's Trustap ID. Must **not** be sent on `POST /transactions` (transaction creation); the endpoint has no header parameters and rejects it.

**`Content-Type` header:** send `Content-Type: application/json` on every call to `api.test.trustap.com/v2`, including POSTs with no request body (`accept_payment`, `confirm_delivery`) — missing on a few calls in testing, easy to skip precisely where there's no body to format. Not needed on GET calls. The one exception is the OAuth token exchange against Trustap's SSO host, which uses `application/x-www-form-urlencoded`.

**Payment URLs:** Never construct a payment URL manually. Use `payment_link` as returned by the API, store it unmodified in the database, and only append `redirect_uri=${window.location.origin}/payment/complete` when redirecting the buyer at checkout time.

**Logging:** Log every outgoing Trustap request and response server-side, redacting the Authorization header.

## Transaction Flow & Statuses

1. Buyer creates transaction → status `joined`.
2. Buyer pays on Trustap's hosted page → redirected back to `/payment/complete`.
3. Dashboard syncs each transaction against Trustap on load; status moves `joined` → `paid` once payment clears.
4. Seller clicks **Accept Payment** (`POST /transactions/{id}/accept_payment`, `Trustap-User: <seller_id>`) → status moves to `payment_accepted`, funds held in escrow. This step does not happen automatically — it requires the explicit call.
5. Seller ships and clicks **Add Tracking** (`POST /transactions/{id}/track`, `Trustap-User: <seller_id>`) — only available once status is `payment_accepted`.
6. Buyer clicks **Confirm Delivery** (`POST /transactions/{id}/confirm_delivery`, `Trustap-User: <buyer_id>`).
7. If the seller upgrades from a guest account via OAuth and claims the transaction, show a "Claimed" indicator under the status badge.

Transaction IDs are strings (`"tx_..."`), not numbers.

## Database Schema

Two Supabase tables: `listings` and `transactions` (linked by `listing_id`). RLS is open on both — no user auth for this prototype.

## Architecture Notes

- Trustap proxy logic lives in TanStack Start server functions (`createServerFn`), exposed to the client via `src/lib/trustap.functions.ts`; the underlying implementation is `src/lib/trustap.server.ts`.
- API key, OAuth client ID, and OAuth client secret stay server-side only.
- Dashboard uses Supabase realtime and re-syncs Trustap status on load.
- Design system: Geist fonts, HSL-based design tokens in `src/styles.css`.

## Open Items to Confirm Before Build

- **OAuth redirect URI registration.** Confirm the exact redirect URI(s) to register for the OAuth client (`/oauth/callback`), and whether Trustap's SSO accepts a wildcard path pattern for this environment or requires an exact match per domain. This is separate from the payment redirect handled via `payment_link` above — don't conflate the two registrations.
- **Redirect URI visibility.** The app should surface its own computed redirect URI (e.g. in the Dashboard) so it can be copied into Trustap's client configuration, rather than requiring it to be read from source or logs.
- **Status labeling.** `paid` and `joined` should read as distinct states in the UI — `joined` as "awaiting payment," `paid` as an action-required state for the seller (payment received, awaiting acceptance) — to avoid the two being visually indistinguishable.
```

## Moving to Production

When you are ready to process real transactions in you application, complete the following steps.

1. Contact your Trustap integration specialist to get access to your production Dashboard. In your production Dashboard, find your Trustap [production credentials](/docs/intro/auth#find-your-authentication-credentials).
2. In your platform settings, swap your Sandbox credentials for your Live Production credentials:


* TRUSTAP_API_KEY: Replace `capi_test_...` with `capi_...`
* TRUSTAP_CLIENT_SECRET: Replace `cs_test_...` with `cs_...`


(Note: Your TRUSTAP_CLIENT_ID starting with `cid_` remains unchanged across both environments.)

1. Prompt the Agent: Send this message in your builder chat:


```
I have updated my Trustap API Key and Client Secret to production values in our project settings.
Please confirm that all Trustap API calls and SSO authentication flows are pointing to the 
production environment ([https://api.trustap.com/v2/](https://api.trustap.com/v2/) and [https://sso.trustap.com/auth/realms/trustap](https://sso.trustap.com/auth/realms/trustap)).
```

## Debugging

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.

### Common things that go wrong

* `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.
* `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 `API_KEY`.
* `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.


### What to send us when you ask for help

Send the following pieces of information to our support team when looking for help.

1. The URL you were calling (e.g. https://api.stage.trustap.com/v1/orders)
2. The method (GET, POST, PUT, PATCH, DELETE)
3. The status code (the three-digit number)
4. The error message (the text that came back)
5. What you were trying to do in plain English


Additionally, try to provide the following if you can.

1. Your transaction ID.
2. A copy of what you sent (your request body — no real API keys or passwords)


## Disclaimer

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.

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.