SDK

import { Icpay, IcpayError } from '@ic-pay/icpay-sdk'

const icpay = new Icpay({
  publishableKey: process.env.NEXT_PUBLIC_ICPAY_PK!,

  // actorProvider + connected wallet are required only when calling
  // createPayment or createPaymentUsd (e.g. Plug, Internet Identity, Oisy)
})

try {
  // Add your code here
} catch (e) {
  if (e instanceof IcpayError) {
    // Handle gracefully
  }
}

import { Icpay } from '@ic-pay/icpay-sdk'

// If you want a drop-in wallet selector, use the widget's helper:
// import { createWalletSelect } from '@ic-pay/icpay-widget'
// const walletSelect = createWalletSelect()

const icpay = new Icpay({
  publishableKey: process.env.NEXT_PUBLIC_ICPAY_PK!,
  actorProvider: (canisterId, idl) => /* return agent-js actor from your wallet */
    walletSelect.getActor({ canisterId, idl, requiresSigning: true, anon: false }),
  connectedWallet: { owner: '<principal-id>' },
})

const tx = await icpay.createPayment({
  tokenShortcode: 'ic_icp', // primary way (server resolves token ledger/chain from shortcode)
  amount: '150000000', // smallest unit (e.g. 1.5 ICP with 8 decimals)
  metadata: { myProductId: '511234', myOrderId: '511234', anyInternalField: 'allowed' },
})

const res = await icpay.createPaymentUsd({
  usdAmount: 5,
  tokenShortcode: 'ic_icp',
  metadata: { context: 'tip-jar', myProductId: '511234', myOrderId: '511234', anyInternalField: 'allowed' },
})

// Attempts X402 flow first; falls back to regular USD flow if not available
const out = await icpay.createPaymentX402Usd({
  usdAmount: 10,
  tokenShortcode: 'ic_icp',
  metadata: { context: 'subscription' },
})

// If X402 responds with Payment Required (402), the SDK will handle header signing
// and settlement, then wait for terminal status, emitting events along the way.

// Get list of Verified Ledgers
const ledgers = await icpay.getVerifiedLedgers()
// Get Ledger Canister Id by Symbol string. eg. ckUSDC or ICP
const bySymbol = await icpay.getLedgerCanisterIdBySymbol('ICP')
// Get all information (eg. decimals, current price, ...) about a ledger by passing a Ledger Canister Id (eg. ICP ledger id is 'ryjl3-tyaaa-aaaaa-aaaba-cai')
const info = await icpay.getLedgerInfo('ryjl3-tyaaa-aaaaa-aaaba-cai')
// Fetch all ledgers with current price for 1 token unit
const priced = await icpay.getAllLedgersWithPrices()
// Get number of token that is needed for a fixed price in USD
const calc = await icpay.calculateTokenAmountFromUSD({ usdAmount: 10, ledgerCanisterId: info.canisterId })

type LedgerBalance = {
  ledgerId: string
  ledgerName: string
  ledgerSymbol: string
  canisterId: string
  eip3009Version?: string | null
  x402Accepts?: boolean
  balance: string                 // smallest unit
  formattedBalance: string        // human-readable
  decimals: number
  currentPrice?: number
  lastPriceUpdate?: Date
  lastUpdated: Date
  // Chain metadata (when available)
  chainId?: string
  chainName?: string | null
  rpcUrlPublic?: string | null
  chainUuid?: string | null
  // Required amount helpers (when amount/amountUsd passed)
  requiredAmount?: string
  requiredAmountFormatted?: string
  hasSufficientBalance?: boolean
  logoUrl?: string | null
}

const providers = icpay.getWalletProviders()
if (icpay.isWalletProviderAvailable('plug')) {
  await icpay.connectWallet('plug')
}
const principal = icpay.getAccountAddress()

const all = await icpay.getExternalWalletBalances({
  network: 'evm',               // 'evm' | 'ic'
  address: '0xabc...',          // or principal: 'aaaa-bbbb...'
  amountUsd: 10,                // optional: compute requiredAmount per ledger
  chainShortcodes: ['base-sep'],// optional filter
  tokenShortcodes: ['base_usdcoin'], // optional filter by token shortcode
})
for (const b of all.balances) {
  console.log(b.ledgerSymbol, b.formattedBalance, b.hasSufficientBalance)
}

const b = await icpay.getSingleLedgerBalance('ryjl3-tyaaa-aaaaa-aaaba-cai')
console.log(b.ledgerSymbol, b.formattedBalance, b.currentPrice)

// Example: pack EVM id (bytes32) for custom contract calls
const idHex = icpay.packEvmId('42', 1234)

const unsubscribe = icpay.on('icpay-sdk-transaction-completed', (detail) => {
  // e.g., show success toast, update UI
})

icpay.on('icpay-sdk-transaction-mismatched', (detail) => {
  // detail.requestedAmount, detail.paidAmount
})

// Later
unsubscribe()

type SdkPayment = {
  id: string
  accountId: string
  paymentIntentId: string
  transactionId: string | null
  transactionSplitId?: string | null
  canisterTxId: number | null
  amount: string
  ledgerCanisterId: string
  ledgerTxId?: string | null
  accountCanisterId?: number | null
  basePaymentAccountId?: string | null
  status: 'pending' | 'completed' | 'failed' | 'canceled' | 'refunded' | 'mismatched'
  // Optional clarity fields on webhook payloads and some responses
  requestedAmount?: string | null // from payment_intent.amount
  paidAmount?: string | null // from transaction.amount
  invoiceId: string | null
  metadata: Record<string, unknown>
  createdAt: string
  updatedAt: string
}

const onCompleted = (evt: any) => {
  const detail = evt && typeof evt === 'object' ? (evt as any).detail ?? evt : evt
  // e.g., show success toast, update UI
}

icpay.addEventListener('icpay-sdk-transaction-completed', onCompleted)

// Later
icpay.removeEventListener('icpay-sdk-transaction-completed', onCompleted)