> ## 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.

# Creating Payments

> Create payment requests with POST /payments and track them from pending to completed.

## Create a payment

`POST /payments` — Initialize a new payment request. Tribridge derives the merchant from your `x-api-key` header and returns a unique `id` plus a hosted `checkout_url` to send to your customer. The settlement chain is chosen later, when the deposit wallet is generated.

### Step 1 — Send the request

Include your API key and a JSON body:

<CodeGroup>
  ```bash Example request theme={null}
  curl -X POST https://tribridge.onrender.com/payments \
    -H "Content-Type: application/json" \
    -H "x-api-key: tri_test_your_key_here" \
    -d '{
      "amount": 99.00,
      "currency": "USD",
      "redirect_url": "https://yoursite.com/order/8912",
      "description": "Order #8912"
    }'
  ```

  ```json Example response — 201 Created theme={null}
  {
    "id": "b3f1c2a0-1d4e-4f2a-9c8b-2e7a6f5d4c3b",
    "amount": "99.00",
    "currency": "USD",
    "status": "pending",
    "is_test": true,
    "redirect_url": "https://yoursite.com/order/8912",
    "checkout_url": "https://tribridge.onrender.com/gateway?payment_id=b3f1c2a0-1d4e-4f2a-9c8b-2e7a6f5d4c3b",
    "expires_at": "2026-08-25T12:30:00.000Z",
    "created_at": "2026-08-25T12:00:00.000Z"
  }
  ```
</CodeGroup>

### Headers

| Header | Value |
| - | - |
| `x-api-key` | Your `tri_test_...` or `tri_live_...` key (required) |
| `Content-Type` | `application/json` |

### Body parameters

| Field | Type | Required | Description |
| - | - | - | - |
| `amount` | number | Yes | The amount to charge, e.g. `99.00`. |
| `currency` | string | Yes | Fiat or token ticker, e.g. `USD`, `USDC`, `SOL`. |
| `redirect_url` | string | No | Where the customer is sent after the payment completes. |
| `description` | string | No | A human-readable note shown on the checkout page. |

<Note>
  The settlement chain (`solana` or `sui`) is selected when the deposit wallet is generated via `POST /payments/checkout/:id/generate-wallet` — it is **not** a field of the create request.
</Note>

### Step 2 — Send the customer to checkout

Redirect the customer (or show a link/QR) to the `checkout_url`. There they select a chain, see the one-time deposit address and exact amount, and pay from any wallet.

### Step 3 — Handle the outcome

* **Test mode:** click **Simulate Payment** on the checkout page — no real chain involved.
* **Live mode:** wait for the real on-chain transfer. Tribridge detects finality and fires `payment.confirmed`, then `payment.completed` to your webhook.

After completion the customer is sent to your `redirect_url` (if provided). **Never trust the redirect alone** — always confirm via webhook or by fetching the payment status server-side.

## Possible errors

| Code | Meaning | What to do |
| - | - | - |
| `400` | Missing/invalid `amount` or `currency` | Check required fields and types. |
| `401` | Missing or invalid API key | Verify the `x-api-key` header and that the keypair is active. |
| `429` | Rate limit (100 req/min per IP) | Slow down and retry with backoff. |

## Related pages

<CardGroup cols={2}>
  <Card title="Payment Lifecycle" icon="route" href="/lifecycle">
    What happens to a payment after creation, state by state.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Get notified the moment each state changes.
  </Card>
</CardGroup>


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