Skip to main content

Quick Start

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

Initialize the Client​

import { ZenPays } from '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: 1000, // Amount in smallest currency unit (e.g., cents)
  currency: 'USD',
  description: 'Premium subscription',
  customerDetails: {
    name: 'John Doe',
    email: 'john@example.com',
  },
})

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

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: 'credit_card',
    cardNumber: '4111111111111111',
    expiryMonth: '12',
    expiryYear: '2025',
    cvv: '123',
    cardHolderName: 'John Doe',
  },
})

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 '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 '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, // $29.99
      currency: 'USD',
      description: 'Pro Plan - Monthly',
      metadata: {
        userId: 'user_123',
        planId: 'pro_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: 'credit_card',
        cardNumber: '4111111111111111',
        expiryMonth: '12',
        expiryYear: '2026',
        cvv: '123',
        cardHolderName: 'Jane Smith',
      },
    })

    // 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​