Skip to main content

Payment Links API

Create and manage shareable payment links for accepting USDC payments on Base network.

Endpoints​

POST /v1/payment-links

Request:

{
  "userId": "user_...",
  "amount": 50.0,
  "description": "Website Development Services",
  "expiresInHours": 168
}

Response:

{
  "id": "link_...",
  "amount": 50.0,
  "currency": "USDC",
  "description": "Website Development Services",
  "url": "https://pay.blockia.com/link/abc123...",
  "aiUrl": "https://pay.blockia.com/x402/abc123...",
  "network": "base-sepolia",
  "status": "ACTIVE",
  "expiresAt": "2024-01-08T10:00:00.000Z",
  "createdAt": "2024-01-01T10:00:00.000Z"
}

GET /v1/payment-links/\{id\}?userId=user_...

Response:

{
  "id": "link_...",
  "amount": 50.0,
  "currency": "USDC",
  "description": "Website Development Services",
  "url": "https://pay.blockia.com/link/abc123...",
  "aiUrl": "https://pay.blockia.com/x402/abc123...",
  "network": "base-sepolia",
  "status": "ACTIVE",
  "expiresAt": "2024-01-08T10:00:00.000Z",
  "createdAt": "2024-01-01T10:00:00.000Z",
  "updatedAt": "2024-01-01T10:00:00.000Z"
}

GET /v1/payment-links?userId=user_...&limit=20&cursor=...&status=ACTIVE

Response:

{
  "links": [
    {
      "id": "link_...",
      "amount": 50.0,
      "currency": "USDC",
      "description": "Website Development Services",
      "url": "https://pay.blockia.com/link/abc123...",
      "aiUrl": "https://pay.blockia.com/x402/abc123...",
      "network": "base-sepolia",
      "status": "ACTIVE",
      "expiresAt": "2024-01-08T10:00:00.000Z",
      "createdAt": "2024-01-01T10:00:00.000Z"
    }
  ],
  "nextCursor": "eyJpZCI6ImxpbmtfLi4uIiwib2Zmc2V0IjoyMH0",
  "totalCount": 45,
  "activeCount": 12,
  "pagination": {
    "hasNextPage": true,
    "limit": 20
  }
}

GET /v1/payment-links/stats?userId=user_...

Response:

{
  "totalLinks": 45,
  "activeLinks": 12,
  "paidLinks": 28,
  "expiredLinks": 5,
  "totalEarnings": 1250.5,
  "currency": "USDC"
}

GET /api/v1/public/payment-links/{linkId}/data

Response:

{
  "linkId": "abc123...",
  "merchantName": "freelancer@example.com",
  "amount": 50.0,
  "currency": "USDC",
  "network": "base-sepolia",
  "recipientAddress": "0x742d35Cc...",
  "description": "Website Development Services",
  "status": "ACTIVE",
  "expiresAt": "2024-01-08T10:00:00.000Z"
}

POST /api/v1/public/payment-links/{linkId}/complete

Request:

{
  "transactionHash": "0x1234567890abcdef...",
  "clientWalletAddress": "0xabcdef..."
}

Response:

{
  "success": true,
  "linkId": "abc123...",
  "status": "PENDING"
}

Error Responses​

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "amount",
      "issue": "must be positive number"
    }
  }
}

Business Rules​

  • Amount: 0 < amount ≤ 1,000,000 USDC (max 6 decimals)
  • Description: 1-500 characters
  • Expiration: 1 hour to 90 days
  • Currency: USDC only
  • Network: Base Sepolia (testnet) or Base (mainnet)