Skip to main content
POST
Create a checkout session
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).
On Windows, single-quoted -d '{...}' bodies fail in cmd.exe. Use escaped quotes instead:
cmd.exe
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 while the payment is pending.
3

Handle the outcome

Test mode: the customer (or your server, via Simulate payment) completes it instantly. Live mode: Tribridge watches the chain and fires your webhook. Fulfill only on a verified payment.completed event (see Webhooks).

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.
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 server-side.

Authorizations

x-api-key
string
header
default:tri_test_your_key_here
required

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.

Body

application/json
amount
number
required

Amount to charge. Minimum $0.50. The payer settles this amount 1:1 in the stablecoin chosen at checkout.

Required range: x >= 0.5
Example:

99

currency
string
default:USD

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.

Example:

"USDC"

redirect_url
string<uri>

Where the customer is sent after the payment completes. Always confirm fulfillment via webhook or a server-side status fetch — never trust the redirect.

Example:

"https://yoursite.com/order/8912"

description
string

Human-readable note shown on the checkout page.

Example:

"Order #8912"

customer_email
string<email>

Payer email. When present, the payer automatically receives a payment receipt once the payment completes.

Maximum string length: 254
Example:

"jane@example.com"

customer_name
string

Payer name, printed on the receipt.

Maximum string length: 120
Example:

"Jane Doe"

coin_symbol
enum<string>
default:USDC

Stablecoin the checkout defaults to. The customer can still switch assets at checkout for payments created with this API.

Available options:
USDC,
USDT
processing_fee_enabled
boolean
default:false

Adds the 1% processing-fee surcharge to the checkout total. Omit to fall back to your merchant dashboard setting.

Response

Checkout session created

A payment (checkout session) as returned on creation.

id
string<uuid>

Payment id.

merchant_id
string<uuid>
amount
string

Merchant-facing base amount (string decimal).

Example:

"99.00"

currency
string

Display label shown on the checkout page.

Example:

"USDC"

description
string
status
enum<string>
Available options:
pending,
completed,
expired,
cancelled
Example:

"pending"

is_test
boolean

Derived from the API key used to create the payment.

redirect_url
string<uri> | null
coin_symbol
enum<string>
Available options:
USDC,
USDT
processing_fee_enabled
boolean
customer_email
string<email> | null
customer_name
string | null
expires_at
string<date-time>
created_at
string<date-time>
checkout_url
string<uri>

Hosted checkout URL to send the customer to.