API Getting Started

Authentication

Base URL: https://api.unuspay.com/api/v1

Get Your API Key

1. Log in to the Dashboard
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Copy the secret key immediately — it’s shown only once

Make Authenticated Requests

Include your API key in the Authorization header:

curl -X GET https://api.unuspay.com/api/v1/payment_links \
  -H "Authorization: Bearer sk_ak_xxx_xxxxxxxxxxxxxxxxxxxxxxxx"

Response Format

All successful responses return:

{
  "status": "success",
  "data": { ... }
}

Your First Request

List your payment links:

curl -X GET https://api.unuspay.com/api/v1/payment_links \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "status": "success",
  "data": [
    {
      "link_id": "lnk_abc123xyz456",
      "slug": "pay-1772692608317-dzejsd",
      "item_name": "Pro Subscription",
      "amount": "99.00",
      "currency": "USD",
      "link_type": "reusable",
      "status": 1,
      "created_at": "2024-03-01T10:00:00Z"
    }
  ]
}

Payment URL: Construct the customer-facing payment link using the slug:

https://app.unuspay.com/pay/{slug}

Core Concepts

Payment Link

A reusable or single-use URL for collecting payments. Specifies the item name, amount, currency, and which wallet set receives funds. Share the link with customers or embed it in your checkout flow.

Order

Created when a customer initiates payment from a link. Tracks the payment lifecycle through states: pending → processing → completed or failed. Contains the payer’s wallet address and requested payment details.

Transaction

An on-chain token transfer that fulfills an order. Records the transaction hash, chain ID, token address, and confirmed amount. A single order may have multiple transaction attempts before completion.

Wallet Set

A collection of your organization’s wallets that defines which blockchains and tokens you accept. Each payment link references a wallet set to determine available payment options for customers.

Payment Flow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Payment Link   │────▶│     Order       │────▶│  Transaction    │
│  (you create)   │     │ (customer init) │     │  (on-chain tx)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘

1. Create a payment link — specify amount, currency, wallet set
2. Customer visits link — selects preferred chain and token
3. Order created — status: pending
4. Customer sends payment — on-chain transfer to your wallet
5. Transaction confirmed — order status: completed
6. Webhook fires — your server receives order.completed event