Payments API

The Payments API allows you to create and manage payment intents and transactions.

Methods

createPaymentIntent

Create a new payment intent.

const intent = await zenpays.payments.createPaymentIntent({
  amount: 1000,
  currency: 'USD',
  description: 'Order #123',
  customerDetails: {
    name: 'John Doe',
    email: 'john@example.com',
  },
  metadata: {
    orderId: 'order_123',
  },
})

Parameters:

Field	Type	Required	Description
amount	number	Yes	Amount in smallest currency unit
currency	string	Yes	Three-letter currency code
description	string	No	Payment description
customerDetails	CustomerDetails	No	Customer information
paymentMethod	PaymentMethodType	No	Preferred payment method
metadata	Record<string, unknown>	No	Custom metadata
expiresIn	number	No	Expiration time in seconds
successUrl	string	No	Redirect URL on success
cancelUrl	string	No	Redirect URL on cancel

Returns: CreatePaymentIntentResponse

---

getPaymentIntent

Get payment intent details (authenticated).

const intent = await zenpays.payments.getPaymentIntent('pi_xxx')

Returns: PaymentIntent

---

getPublicPaymentIntent

Get payment intent details (public, no authentication required).

const intent = await zenpays.payments.getPublicPaymentIntent('pi_xxx', token?)

Returns: PaymentIntent

---

confirmPayment

Confirm a payment intent with payment details.

const result = await zenpays.payments.confirmPayment('pi_xxx', {
  customerDetails: {
    name: 'John Doe',
    email: 'john@example.com',
    address: { country: 'US' },
  },
  paymentMethodDetails: {
    type: 'credit_card',
    cardNumber: '4111111111111111',
    expiryMonth: '12',
    expiryYear: '2025',
    cvv: '123',
  },
})

Parameters:

Field	Type	Required	Description
customerDetails	CustomerDetails	Yes	Customer information
deviceInfo	DeviceInfo	No	Device fingerprint data
paymentMethodDetails	PaymentMethodDetails	No	Payment method details
paymentRailId	string	No	Specific payment rail to use
quoteId	string	No	Quote ID for crypto payments

Returns: ConfirmPaymentResponse

---

processPayment

Process a payment directly.

const result = await zenpays.payments.processPayment('pi_xxx', {
  customerDetails: { ... },
  paymentMethodDetails: { ... },
})

---

cancelPaymentIntent

Cancel a payment intent.

const intent = await zenpays.payments.cancelPaymentIntent('pi_xxx')

---

updateIntelligence

Update device intelligence for fraud prevention.

await zenpays.payments.updateIntelligence('pi_xxx', {
  userAgent: navigator.userAgent,
  screenWidth: window.screen.width,
  screenHeight: window.screen.height,
  deviceFingerprint: 'fp_xxx',
})

---

getTransaction

Get a transaction by ID.

const transaction = await zenpays.payments.getTransaction('txn_xxx')

Returns: Transaction

---

getTransactionsByIntent

Get all transactions for a payment intent.

const transactions = await zenpays.payments.getTransactionsByIntent('pi_xxx')

Returns: Transaction[]

---

listTransactions

List transactions with filters.

const { data, total } = await zenpays.payments.listTransactions({
  status: 'succeeded',
  from: '2024-01-01',
  to: '2024-12-31',
  limit: 50,
})

Filters:

Field	Type	Description
status	PaymentStatus | PaymentStatus[]	Filter by status
paymentMethod	PaymentMethodType | PaymentMethodType[]	Filter by payment method
currency	string	Filter by currency
customerId	string	Filter by customer
minAmount	number	Minimum amount
maxAmount	number	Maximum amount
from	string | Date	Start date
to	string | Date	End date

Returns: PaginatedResponse<Transaction>

---

getTransactionAnalytics

Get transaction analytics.

const analytics = await zenpays.payments.getTransactionAnalytics('30d')

Returns: TransactionAnalytics

---

exportTransactions

Export transactions to CSV or XLSX.

const downloadUrl = await zenpays.payments.exportTransactions(
  { status: 'succeeded', from: '2024-01-01' },
  'csv'
)

Types

PaymentIntent

interface PaymentIntent {
  id: string
  merchantId: string
  merchantName?: string
  merchantLogo?: string
  description?: string
  amount: number
  currency: string
  status: PaymentStatus
  customerName?: string
  customerEmail?: string
  customerPhone?: string
  processingFee?: number
  expiresAt?: string
  metadata?: Record<string, unknown>
  createdAt?: string
  updatedAt?: string
}

PaymentStatus

type PaymentStatus
  = | 'pending'
    | 'processing'
    | 'succeeded'
    | 'failed'
    | 'cancelled'
    | 'expired'
    | 'confirmed'

PaymentMethodType

type PaymentMethodType
  = | 'crypto'
    | 'credit_card'
    | 'debit_card'
    | 'net_banking'
    | 'upi'
    | 'wallet'
    | 'bank_transfer'
    | 'mobile_money'