verify() & refund()

verify()

Checks the current status of a transaction. Always call this server-side before fulfilling an order — never trust the return URL alone.

Signature

zirzir.verify(txRef: string): Promise<Transaction>

Parameters

Parameter	Type	Description
txRef	string	Your transaction reference passed to charge()

Example

TypeScript

const tx = await zirzir.verify('invoice_2024_001')

switch (tx.status) {
  case 'success':
    await fulfillOrder(tx.txRef)
    break
  case 'pending':
    // Payment still in progress — check again or wait for webhook
    break
  case 'failed':
    // Payment failed — show error to customer
    break
}

Python

tx = client.verify("invoice_2024_001")

if tx.status == "success":
    fulfill_order(tx.tx_ref)
elif tx.status == "pending":
    pass  # wait for webhook
else:
    raise PaymentFailedError(tx.provider_message)

Go

tx, err := client.Verify(ctx, "invoice_2024_001")
if err != nil {
    log.Fatal(err)
}

if tx.Status == zirzir.StatusSuccess {
    fulfillOrder(tx.TxRef)
}

Polling vs Webhooks

For USSD-based providers (Telebirr, CBEBirr, M-Pesa), charge() returns immediately while the customer completes payment on their phone. You have two options:

Option A: Webhook (Recommended) Configure callbackUrl in charge() and wait for the transaction.success event.

Option B: Poll Call verify() every few seconds until status changes from pending. Keep polling intervals reasonable (5-10 seconds) and set a timeout.

async function pollUntilComplete(txRef: string, maxAttempts = 12): Promise<Transaction> {
  for (let i = 0; i < maxAttempts; i++) {
    const tx = await zirzir.verify(txRef)
    if (tx.status !== 'pending') return tx
    await sleep(5000) // 5 second intervals
  }
  throw new Error('Payment timed out')
}

---

refund()

Issues a full or partial refund for a completed transaction.

Not all providers support programmatic refunds. Check the Provider Guides for each provider’s refund capabilities. Telebirr and CBEBirr refunds, for example, require manual processing through their merchant portal.

Signature

zirzir.refund(txRef: string, params?: RefundParams): Promise<Refund>

Parameters

Parameter	Type	Required	Description
txRef	string	Yes	Transaction reference to refund
params.amount	number	No	Partial refund amount. Omit for full refund
params.reason	string	No	Reason for refund. Passed to provider if supported

Return Value

interface Refund {
  id: string
  transactionId: string
  txRef: string
  amount: number           // Amount refunded
  currency: string
  status: 'pending' | 'success' | 'failed'
  provider: ProviderName
  reason: string | null
  createdAt: string
}

Examples

TypeScript

// Full refund
const refund = await zirzir.refund('invoice_2024_001')

// Partial refund (250 ETB of a 500 ETB transaction)
const partialRefund = await zirzir.refund('invoice_2024_001', {
  amount: 250,
  reason: 'Customer returned half the order'
})

Python

# Full refund
refund = client.refund("invoice_2024_001")

# Partial refund
refund = client.refund(
    "invoice_2024_001",
    amount=250,
    reason="Customer returned half the order"
)

Go

// Full refund
refund, err := client.Refund(ctx, "invoice_2024_001", nil)

// Partial refund
refund, err := client.Refund(ctx, "invoice_2024_001", &zirzir.RefundParams{
    Amount: 250,
    Reason: "Customer returned half the order",
})

Provider Refund Support Matrix

Provider	Programmatic Refund	Partial Refund	Notes
Chapa	Yes	Yes	Full API support
Santim	Yes	No	Full refunds only
Telebirr	No	No	Manual via merchant portal
CBEBirr	No	No	Manual via merchant portal
M-Pesa	Yes	Yes	Via M-Pesa Reversal API
Awash	No	No	Manual

Errors

Error	Description
ZirzirRefundNotSupportedError	Provider doesn’t support programmatic refunds
ZirzirRefundAmountExceededError	Refund amount exceeds original transaction amount
ZirzirTransactionNotRefundableError	Transaction is not in a refundable state