API Reference

Complete endpoint reference for the Unter payment gateway API.

Authentication

Authenticated endpoints require an API key sent via one of two headers:

Header	Format
X-API-Key	unter_<40 hex chars>
Authorization	Bearer unter_<40 hex chars>

Permissions

API keys are assigned specific permissions. Endpoints enforce permissions via attributes on the controller.

Permission	Grants Access To
create_payments	Creating payment requests
view_payments	Listing and viewing payment requests
manage_payments	Updating and cancelling payment requests
manage_webhooks	Viewing, updating, and testing webhook settings

Endpoints marked "any" below require a valid API key but no specific permission.

Rate Limits

Tier	Scope	Limit	Key
Public read	GET on /api/public/*	60 / min	Client IP
Public write	POST/PUT/PATCH/DELETE on /api/public/*	20 / min	Client IP
API key	All /api/* (non-public)	300 / min	API key

When rate limited, the API returns HTTP 429 with Retry-After and X-RateLimit-Limit headers.

Public Endpoints

These endpoints require no authentication. They are used by the checkout widget and can be called from any origin.

Method	Path	Description
GET	/api/health	Health check. Returns {"status": "ok"}.
GET	/api/public/chains	List all supported blockchain networks.
GET	/api/public/chains/{id}	Get details for a specific chain.
GET	/api/public/chains/{id}/tokens	List tokens available on a specific chain.
GET	/api/public/payment-requests/{id}	View payment request details (by UUID or shortcode).
GET	/api/public/payment-requests/{id}/status	Get current payment status (for polling).
GET	/api/public/payments/{id}	View details for a specific payment.
POST	/api/public/payment-requests/{id}/payments	Submit a payment (transaction hash) for a payment request.
POST	/api/public/payment-requests/{id}/routes	Get available payment routes (swap/bridge options).
POST	/api/public/payment-requests/{id}/balances/essential	Quick balance check for connected wallet.
POST	/api/public/payment-requests/{id}/balances/extended	Full balance check with extended route options.
POST	/api/public/build-transaction	Build an unsigned blockchain transaction for wallet signing.
POST	/api/public/check-approval	Check if an ERC-20 token approval is needed.
POST	/api/public/check-transaction-status	Check on-chain transaction status.
POST	/api/public/discover-wallet-tokens	Discover tokens held by a wallet address.

Merchant Endpoints (Authenticated)

These endpoints require a valid API key via the X-API-Key or Authorization header.

Payment Requests

Method	Path	Permission	Description
POST	/api/payment-requests	create_payments	Create a new payment request.
GET	/api/payment-requests	view_payments	List all payment requests (filterable).
GET	/api/payment-requests/{id}	view_payments	Get details for a specific payment request.
PATCH	/api/payment-requests/{id}	manage_payments	Update a payment request.
POST	/api/payment-requests/{id}/cancel	manage_payments	Cancel an active payment request.

Chains & Tokens

Method	Path	Permission	Description
GET	/api/chains	any	List supported chains (authenticated view).
GET	/api/chains/{id}/tokens	any	List tokens on a specific chain.

Webhooks

Method	Path	Permission	Description
GET	/api/webhooks	manage_webhooks	Get current webhook configuration.
PUT	/api/webhooks	manage_webhooks	Update webhook URL, secret, and event subscriptions.
POST	/api/webhooks/test	manage_webhooks	Trigger a test webhook delivery.

Amount Format

All monetary amounts in API responses use a consistent structure:

{
  "raw": "1500000",
  "formatted": "1.500000",
  "decimals": 6
}

Field	Type	Description
raw	string	Amount in the token's smallest unit
formatted	string	Human-readable representation with full decimal precision
decimals	int	Number of decimal places for the token

The formatted field always includes trailing zeros to match the token's precision. For example, a token with 6 decimals will format 1000000 raw as "1.000000", not "1".

Address Validation

Wallet addresses submitted in payment requests are validated per chain type:

Chain Type	Validation	Example
EVM (Ethereum, Polygon, Base, BSC)	Hex, 42 chars: ^0x[0-9a-fA-F]{40}$	0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
Solana	Base58, 32-44 chars	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
TRON	Starts with T, 34 chars	TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t