> ## 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://tribridge.onrender.com. Server-side calls 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. 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.

# Payment Lifecycle

> Every payment state from pending to completed, what triggers it, and what you should do.

A payment moves through up to five states. Your webhook endpoint is notified at each transition — build your order logic around these events, not around the customer's redirect.

<Steps>
  <Step title="Pending">
    Created via `POST /payments`. Tribridge returns the `id` and `checkout_url`. **No chain activity yet** — the customer hasn't paid anything.

    *What you do:* store the payment `id` against your order and send the customer to `checkout_url`.
  </Step>

  <Step title="Address generated">
    The customer opens checkout and selects a chain (`solana` or `sui`). Tribridge derives a **one-time deposit wallet** and displays it with the exact amount.

    *What you do:* nothing — but you can show a "waiting for payment" state in your own UI.
  </Step>

  <Step title="Confirmed">
    The on-chain transfer reaches finality. Tribridge detects it (Helius webhook on Solana, polling listener on Sui) and emits the `payment.confirmed` webhook.

    *What you do:* mark the order as paid in your system. Only trust this after verifying the webhook signature.
  </Step>

  <Step title="Completed (forwarded)">
    Funds are swept from the deposit wallet to your payout wallet (gas paid by Tribridge). The `payment.completed` webhook fires and the customer is redirected to your `redirect_url`.

    *What you do:* fulfill the order. `completed` is the terminal success state.
  </Step>

  <Step title="Expired / Cancelled">
    Terminal states. A payment **expires** if unpaid past its window (`expires_at`), or is **cancelled** manually from the dashboard.

    *What you do:* release held stock / cancel the order. The deposit address is retired and will never be reused.
  </Step>
</Steps>

## Amount mismatches

If the customer sends the wrong amount, the payment doesn't silently succeed — you get explicit events and Tribridge refunds automatically (see [Refunds](/refunds)):

| Event | Meaning |
| - | - |
| `payment.underpaid` | Received less than expected. The received amount is refunded to the payer. |
| `payment.overpaid` | Received more than expected. The surplus is refunded to the payer. |
| `payment.expired` | Nothing arrived before `expires_at`. |

<Tip>
  **Test mode shortcut.** In test mode there is no real chain wait — the checkout page exposes a **Simulate Payment** button that drives the payment straight to `completed` and triggers your test webhook. Use it to validate your integration end-to-end, including your `completed` fulfillment logic.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.