API Getting Started

Authentication

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

Get Your API Key

1. Log in to the Merchant 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

flowchart TD
PL["Merchant create payment link"] --> PV["Customer visit payment page"]
CS["Merchant create checkout session"] --> CV["Customer visit checkout page"]
PV --> ORD["Order created pending"]
CV --> ORD
ORD --> PAY["Customer send on-chain payment"]
PAY --> TX["Transaction confirmed"]
TX --> DONE["Order completed"]
DONE -.-> WH["Unuspay fire webhook event"]

Solid arrows — synchronous flow | Dashed arrows — asynchronous

Payment Link

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

Checkout Session

1. Create a checkout session — specify amount, currency, wallet set via API
2. Redirect customer to the returned checkout_url
3. Customer completes payment on the hosted checkout page
4. Transaction confirmed — session status: complete
5. Webhook fires — your server receives checkout.session.completed event