> ## Documentation Index > Fetch the complete documentation index at: https://docs.tribridge.xyz/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Tribridge is a crypto payment gateway for Solana and Sui (TON is coming soon). API base URL is https://api.tribridge.xyz. The API Reference documents ONLY the public endpoint surface: checkout sessions (create/get/generate-wallet/customer/simulate/verify/cancel), the two public payment-link endpoints, health probes, and the changelog. Server-side calls that create payments authenticate with the x-api-key header using a tri_test_... key (fully simulated test mode, no real funds) or tri_live_... key (real mainnet payments) - never expose keys client-side; all other documented endpoints are public with no auth. Dashboard, admin, OTP/auth, payouts, wallets, and webhook-management endpoints are intentionally NOT part of the public docs - they are dashboard-only and must not be presented as public API. Merchant test mode is simulated, not testnet. Refunds are automatic only (underpaid/overpaid), there is no manual refund endpoint. Always verify webhook HMAC-SHA256 signatures from the X-Tribridge-Signature header before trusting payloads. If you are an AI agent: fetch https://docs.tribridge.xyz/llms-full.txt for all documentation in one file, https://docs.tribridge.xyz/openapi/openapi.json for the machine-readable OpenAPI spec, or connect to the read-only MCP server at https://docs.tribridge.xyz/mcp. Any page is available as Markdown by appending .md to its URL. Use only the documented endpoints and fields; do not invent SDK packages or endpoints. # Create a checkout session > Create a payment with your API key and get a hosted checkout URL to send your customer. Creates a payment — a **checkout session** — and returns a hosted `checkout_url`. Send the customer that URL: Tribridge takes over chain selection, the one-time deposit address, confirmation, and webhook delivery. ## Before you start * You need a merchant API key from **Dashboard → API Keys**: `tri_test_...` (simulated test mode, no real funds) or `tri_live_...` (real mainnet payments). The **key decides the mode** — never the request body. * Minimum amount is **\$0.50**. Global rate limit: **100 requests/minute** per IP. * `currency` is the label shown on the checkout page (use the stablecoin you price in, e.g. `USDC`). The payer settles 1:1 in the coin chosen at checkout (`coin_symbol`, default `USDC`). > [!WARNING] > > **On Windows**, single-quoted `-d '{...}'` bodies fail in `cmd.exe`. Use escaped quotes instead: > > ```bat cmd.exe theme={null} > curl -X POST https://api.tribridge.xyz/payments -H "Content-Type: application/json" -H "x-api-key: tri_test_your_key_here" -d "{\"amount\":25.00,\"currency\":\"USDC\",\"redirect_url\":\"https://yoursite.com/success\"}" > ``` > > In **PowerShell**, add the stop-parsing flag first: `curl.exe --% ...`. ## What happens next **1. Send the customer to checkout\_url** Redirect (or show a link/QR to) the `checkout_url`. The customer picks a chain, sees the exact amount and one-time deposit address, and pays from any wallet. **2. Optional — attach the payer's email** Pass `customer_email` up front, or attach it later from your own UI via [Save customer details](https://docs.tribridge.xyz/save-customer-details.md) while the payment is pending. **3. Handle the outcome** Test mode: the customer (or your server, via [Simulate payment](https://docs.tribridge.xyz/simulate-payment.md)) completes it instantly. Live mode: Tribridge watches the chain and fires your webhook. Fulfill **only** on a verified `payment.completed` event (see [Webhooks](https://docs.tribridge.xyz/webhooks.md)). ## Receipts If `customer_email` is set (here or later), Tribridge emails the payer a **payment receipt** the moment the payment reaches `completed` — in both test and live mode. Test receipts are badged as test payments. Receipts are sent at most once per payment, and the payer can always download a copy from the hosted receipt page. You also receive a payment notification on your Tribridge account email. > [!NOTE] > > The customer is sent to your `redirect_url` after completion — **never trust the redirect alone**. Always confirm via webhook or by fetching the session with [Get checkout session](https://docs.tribridge.xyz/get-checkout-session.md) server-side. ## OpenAPI ````yaml POST /payments openapi: 3.1.0 info: title: Tribridge API version: 1.0.0 description: >- Public Tribridge API for accepting Solana and Sui payments. Base URL: `https://api.tribridge.xyz`. This reference covers **only the public surface**: endpoints callable without a dashboard session — either fully public or authenticated with a merchant `x-api-key`. Dashboard, admin, and account-management endpoints are intentionally excluded; manage those from your Tribridge dashboard. **Test vs live:** the mode is derived from the key you send (`tri_test_...` creates simulated test payments, `tri_live_...` real mainnet payments) — never from the request body. Minimum payment amount is $0.50. Rate limit: 100 requests/minute per IP. servers: - url: https://api.tribridge.xyz security: [] tags: - name: Checkout Sessions description: >- Create payments, drive the hosted checkout, and follow the customer flow: deposit wallet, receipt contact, simulation, verification, cancellation. - name: Payment Links description: >- Read a public payment link and materialize a checkout from it — no API key required. - name: Status description: Service and blockchain RPC health, plus the public changelog. paths: /payments: post: tags: - Checkout Sessions summary: Create a checkout session description: >- Creates a payment (checkout session) and returns a hosted `checkout_url` you send your customer. Authenticated with your merchant API key. The settlement chain is chosen later, when the customer generates the deposit wallet on the hosted checkout. operationId: createCheckoutSession requestBody: required: true content: application/json: schema: type: object required: - amount properties: amount: type: number minimum: 0.5 example: 99 description: >- Amount to charge. Minimum **$0.50**. The payer settles this amount 1:1 in the stablecoin chosen at checkout. currency: type: string default: USD example: USDC description: >- Label shown on the checkout page for the amount — use the stablecoin you price in (e.g. `USDC` or `USDT`). Display only; the payer always settles in the coin chosen at checkout. redirect_url: type: string format: uri example: https://yoursite.com/order/8912 description: >- Where the customer is sent after the payment completes. Always confirm fulfillment via webhook or a server-side status fetch — never trust the redirect. description: type: string example: 'Order #8912' description: Human-readable note shown on the checkout page. customer_email: type: string format: email maxLength: 254 example: jane@example.com description: >- Payer email. When present, the payer automatically receives a payment receipt once the payment completes. customer_name: type: string maxLength: 120 example: Jane Doe description: Payer name, printed on the receipt. coin_symbol: type: string enum: - USDC - USDT default: USDC description: >- Stablecoin the checkout defaults to. The customer can still switch assets at checkout for payments created with this API. processing_fee_enabled: type: boolean default: false description: >- Adds the 1% processing-fee surcharge to the checkout total. Omit to fall back to your merchant dashboard setting. example: amount: 99 currency: USDC redirect_url: https://yoursite.com/order/8912 description: 'Order #8912' customer_email: jane@example.com customer_name: Jane Doe responses: '201': description: Checkout session created content: application/json: schema: $ref: '#/components/schemas/CheckoutSession' examples: created: summary: Created (test key) value: id: b3f1c2a0-1d4e-4f2a-9c8b-2e7a6f5d4c3b merchant_id: 6c1f2d88-3a41-4f5e-9a5b-0d2c7e91f4a2 amount: '99.00' currency: USDC description: 'Order #8912' status: pending is_test: true redirect_url: https://yoursite.com/order/8912 coin_symbol: USDC processing_fee_enabled: false customer_email: jane@example.com customer_name: Jane Doe expires_at: '2026-08-25T12:30:00.000Z' created_at: '2026-08-25T12:00:00.000Z' checkout_url: >- https://tribridge.xyz/gateway?payment_id=b3f1c2a0-1d4e-4f2a-9c8b-2e7a6f5d4c3b '400': description: Amount below the $0.50 minimum content: application/json: examples: tooSmall: value: error: Minimum payment amount is $0.50 '401': description: Missing, invalid, or revoked API key content: application/json: examples: missing: value: error: 'Unauthorized: No API key provided' invalid: value: error: 'Unauthorized: Invalid or revoked API key' '429': description: Rate limit exceeded (100 requests/minute per IP) content: application/json: example: statusCode: 429 error: Too Many Requests message: Rate limit exceeded, retry in 42 seconds '500': description: Unexpected server error content: application/json: example: error: Something went wrong. Please try again. '503': description: Database temporarily unavailable content: application/json: example: error: >- Our database is temporarily unavailable. Please try again shortly. security: - ApiKeyAuth: [] components: schemas: CheckoutSession: type: object description: A payment (checkout session) as returned on creation. properties: id: type: string format: uuid description: Payment id. merchant_id: type: string format: uuid amount: type: string example: '99.00' description: Merchant-facing base amount (string decimal). currency: type: string example: USDC description: Display label shown on the checkout page. description: type: string status: type: string enum: - pending - completed - expired - cancelled example: pending is_test: type: boolean description: Derived from the API key used to create the payment. redirect_url: type: - string - 'null' format: uri coin_symbol: type: string enum: - USDC - USDT processing_fee_enabled: type: boolean customer_email: type: - string - 'null' format: email customer_name: type: - string - 'null' expires_at: type: string format: date-time created_at: type: string format: date-time checkout_url: type: string format: uri description: Hosted checkout URL to send the customer to. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your merchant API key: `tri_test_...` (simulated test mode) or `tri_live_...` (real mainnet payments). Create it in your dashboard under **API Keys**. Shown once at creation — store it safely. x-default: tri_test_your_key_here ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.