Creating Payments - Tribridge

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:

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"
  }'

{
  "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"
}

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.

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.

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.

Payment Lifecycle

What happens to a payment after creation, state by state.

Webhooks

Get notified the moment each state changes.

​Create a payment

​Step 1 — Send the request

​Headers

​Body parameters

​Step 2 — Send the customer to checkout

​Step 3 — Handle the outcome

​Possible errors

​Related pages

Payment Lifecycle

Webhooks

Create a payment

Step 1 — Send the request

Headers

Body parameters

Step 2 — Send the customer to checkout

Step 3 — Handle the outcome

Possible errors

Related pages