Quick Start Guide

Get API Credentials

API keys are provisioned through the admin portal. Each key follows the format unter_<40 hex chars> (46 characters total).

Authenticate requests by including the key in the X-API-Key header:

X-API-Key: unter_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Alternatively, you can use the Authorization header:

Authorization: Bearer unter_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Discover Supported Chains

List all supported blockchain networks. This is a public endpoint — no authentication required.

curl YOUR_API_URL/api/public/chains

Response:

[
  {
    "id": 1,
    "name": "Ethereum",
    "chain_type": "evm",
    "is_active": true
  },
  {
    "id": 2,
    "name": "Polygon",
    "chain_type": "evm",
    "is_active": true
  },
  {
    "id": 3,
    "name": "Solana",
    "chain_type": "solana",
    "is_active": true
  }
]

Get Tokens for a Chain

List available tokens on a specific chain. Also public, no authentication required.

curl YOUR_API_URL/api/public/chains/1/tokens

Response:

[
  {
    "id": 1,
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 6,
    "contract_address": "0xA0b8..."
  },
  {
    "id": 2,
    "symbol": "USDT",
    "name": "Tether USD",
    "decimals": 6,
    "contract_address": "0xdAC1..."
  }
]

Note the id and decimals values — you will need them when creating a payment request.

Create a Payment Request

Create a payment request specifying the amount, destination token, chain, and recipient wallet address. This endpoint requires authentication.

curl -X POST YOUR_API_URL/api/payment-requests \
  -H "Content-Type: application/json" \
  -H "X-API-Key: unter_YOUR_API_KEY_HERE" \
  -d '{
    "amount": "50.00",
    "token_id": 1,
    "chain_id": 1,
    "recipient_address": "0xYourWalletAddress...",
    "external_id": "order-123",
    "redirect_url": "https://shop.example.com/thank-you",
    "cancel_url": "https://shop.example.com/cart"
  }'

Response:

{
  "id": "a1b2c3d4-e5f6-...",
  "shortcode": "abc123",
  "status": "active",
  "amount": {
    "raw": "50000000",
    "formatted": "50.000000",
    "decimals": 6
  },
  "payment_url": "https://cdn.unter.tech/pay/abc123",
  "redirect_url": "https://shop.example.com/thank-you",
  "cancel_url": "https://shop.example.com/cart",
  "external_id": "order-123"
}

Amount Format

Amounts in responses are returned as a structured object with three fields:

Required Permissions

Your API key must have the create_payments permission to use this endpoint.

Redirect Customer to Checkout

Redirect your customer to the payment_url returned in the response. The hosted checkout widget handles wallet connection, token selection, and transaction signing.

# The payment URL follows this pattern:
https://cdn.unter.tech/pay/{shortcode}

# Example:
https://cdn.unter.tech/pay/abc123

The checkout page will:

• Display the payment amount and destination token
• Detect the customer's connected wallet and balances
• Offer routing options (direct transfer or cross-chain swap)
• Build and present the transaction for wallet signing
• Monitor the transaction until confirmed on-chain
• Redirect to your redirect_url on success, or cancel_url on cancellation

Receive Webhook Notification

When the payment is confirmed on-chain, Unter sends a webhook to your configured URL.

{
  "id": "evt_abc123def456...",
  "type": "payment.succeeded",
  "created": 1706000000,
  "data": {
    "object": {
      "id": "pay_...",
      "amount": 50000000,
      "currency": "USDC",
      "status": "succeeded",
      "reference": "order-123"
    }
  }
}

The webhook includes an Unter-Signature header for verification. See the Webhook Integration guide for details on signature verification and retry behavior.