Skip to main content
View as Markdown

Quick Start

Learn how to create your first payment with the ZenPays SDK.

Initialize the Client​

import { ZenPays } from '@zenxdigitalholdings/zenpays'

const zenpays = new ZenPays({
  apiKey: 'your-api-key',
})

Create a Payment Intent​

A payment intent represents a single payment flow. Create one to start accepting payments:

const paymentIntent = await zenpays.payments.createPaymentIntent({
  amount: 100,
  currency: 'INR',
  paymentMethod: 'upi',
  customerEmail: 'john@example.com',
  customerFirstName: 'John',
  customerLastName: 'Doe',
  customerCountry: 'IN',
  description: 'Premium subscription',
})

console.log('Payment Intent ID:', paymentIntent.intentId)
console.log('Payment Page URL:', paymentIntent.paymentPageUrl)

Confirm the Payment​

Once the customer provides payment details, confirm the payment:

const result = await zenpays.payments.confirmPayment(paymentIntent.intentId, {
  customerDetails: {
    name: 'John Doe',
    email: 'john@example.com',
    address: { country: 'US' },
  },
  paymentMethodDetails: {
    type: 'upi',
    vpa: 'john@upi',
  },
})

if (result.status === 'succeeded') {
  console.log('Payment successful!')
}
else if (result.nextAction) {
  // Handle 3D Secure or other required actions
  console.log('Redirect to:', result.nextAction.redirectUrl)
}

Check Payment Status​

const intent = await zenpays.payments.getPaymentIntent(paymentIntent.intentId)

console.log('Status:', intent.status)
// 'pending' | 'processing' | 'succeeded' | 'failed' | 'cancelled'

Handle Webhooks​

Set up webhooks to receive real-time payment updates:

// Register a webhook endpoint
await zenpays.merchants.createWebhook({
  url: 'https://your-site.com/webhooks/zenpays',
  events: [
    'payment.intent.succeeded',
    'payment.intent.failed',
    'refund.completed',
  ],
})

Error Handling​

The SDK throws specific error types for different scenarios:

import { PaymentError, ValidationError, ZenPaysError } from '@zenxdigitalholdings/zenpays'

try {
  await zenpays.payments.createPaymentIntent({
    amount: 1000,
    currency: 'USD',
  })
}
catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message)
  }
  else if (error instanceof PaymentError) {
    console.error('Payment failed:', error.message)
  }
  else if (error instanceof ZenPaysError) {
    console.error('API error:', error.message, error.code)
  }
}

Complete Example​

Here's a complete example bringing it all together:

import { ZenPays, ZenPaysError } from '@zenxdigitalholdings/zenpays'

async function processPayment() {
  const zenpays = new ZenPays({
    apiKey: process.env.ZENPAYS_API_KEY!,
  })

  try {
    // 1. Create payment intent
    const intent = await zenpays.payments.createPaymentIntent({
      amount: 2999,
      currency: 'INR',
      paymentMethod: 'upi',
      customerEmail: 'jane@example.com',
      customerFirstName: 'Jane',
      customerLastName: 'Smith',
      customerCountry: 'IN',
      description: 'Pro Plan - Monthly',
    })

    // 2. Confirm with payment details
    const result = await zenpays.payments.confirmPayment(intent.intentId, {
      customerDetails: {
        name: 'Jane Smith',
        email: 'jane@example.com',
        address: { country: 'US' },
      },
      paymentMethodDetails: {
        type: 'upi',
        vpa: 'jane@upi',
      },
    })

    // 3. Handle result
    if (result.status === 'succeeded') {
      console.log('Payment completed successfully!')
      console.log('Transaction ID:', result.externalTransactionId)
    }
    else if (result.nextAction?.type === 'redirect') {
      console.log('3D Secure required, redirect to:', result.nextAction.redirectUrl)
    }
  }
  catch (error) {
    if (error instanceof ZenPaysError) {
      console.error(`Error [${error.code}]: ${error.message}`)
    }
    throw error
  }
}

processPayment()

Next Steps​