FinFusion

Basic Integration Guide

Getting Started with FinFusion

Learn how to integrate FinFusion's core features into your application. This guide covers the essential steps to get your integration up and running.

Make sure to test thoroughly in the sandbox environment before going live.

Prerequisites

API Keys

Development and Production keys from your dashboard

  • Sandbox API key for testing
  • Production API key for live transactions
  • Webhook signing secret

Development Environment

Required tools and configurations

  • Node.js 14+ or Python 3.7+
  • SSL/TLS enabled server
  • Secure key storage solution
  • Webhook endpoint (HTTPS required)

Basic Features

Authentication

Set up API authentication

// Initialize with environment variables
const finfusion = new FinFusion({
  apiKey: process.env.FINFUSION_API_KEY,
  environment: process.env.FINFUSION_ENV || 'development',
  options: {
    timeout: 30000,
    retries: 3
  }
});

// Test authentication
const authTest = await finfusion.auth.test();
console.log('Connected to FinFusion:', authTest.status);

Payments

Process basic payments

// Create a payment
const payment = await finfusion.payments.create({
  amount: 1000, // Amount in cents
  currency: 'USD',
  description: 'Test payment',
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  },
  metadata: {
    orderId: '12345'
  }
});

// Check payment status
const status = await finfusion.payments.getStatus(payment.id);

// Handle refunds
const refund = await finfusion.payments.refund({
  paymentId: payment.id,
  amount: 1000, // Full refund
  reason: 'customer_request'
});

Customers

Manage customer data

// Create a customer
const customer = await finfusion.customers.create({
  email: 'customer@example.com',
  name: 'John Doe',
  metadata: {
    source: 'web_signup'
  }
});

// Add payment method
const paymentMethod = await finfusion.customers.addPaymentMethod({
  customerId: customer.id,
  type: 'card',
  card: {
    number: '4242424242424242',
    expMonth: 12,
    expYear: 2024,
    cvc: '123'
  }
});

// List customer transactions
const transactions = await finfusion.customers.listTransactions({
  customerId: customer.id,
  limit: 10,
  status: 'completed'
});

Error Handling

Implement proper error handling

try {
  const payment = await finfusion.payments.create({
    amount: 1000,
    currency: 'USD'
  });
} catch (error) {
  if (error.type === 'validation_error') {
    console.error('Invalid payment details:', error.message);
  } else if (error.type === 'api_error') {
    console.error('API error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Webhook Setup

Set up basic webhook handling

// Express webhook handler
app.post('/webhooks', express.raw({type: 'application/json'}), async (req, res) => {
  const signature = req.headers['x-finfusion-signature'];

  try {
    const event = await finfusion.webhooks.constructEvent(
      req.body,
      signature,
      process.env.WEBHOOK_SECRET
    );

    switch (event.type) {
      case 'payment.succeeded':
        await handlePaymentSuccess(event.data);
        break;
      case 'payment.failed':
        await handlePaymentFailure(event.data);
        break;
      default:
        console.log('Unhandled event type:', event.type);
    }

    res.json({received: true});
  } catch (err) {
    console.error('Webhook error:', err.message);
    res.status(400).send('Webhook Error: ' + err.message);
  }
});

Testing Guide

Testing your integration

Test Cards

// Test successful payment
const successPayment = await finfusion.payments.create({
  amount: 1000,
  currency: 'USD',
  card: {
    number: '4242424242424242', // Test success card
    expMonth: 12,
    expYear: 2024,
    cvc: '123'
  }
});

// Test failed payment
const failedPayment = await finfusion.payments.create({
  amount: 1000,
  currency: 'USD',
  card: {
    number: '4000000000000002', // Test failure card
    expMonth: 12,
    expYear: 2024,
    cvc: '123'
  }
});
Never use production API keys in development or test environments.